AIに読ませるドキュメント体系──L0〜L6と「正本ルール」
AIエージェントの出力がぶれるとき、原因はモデルの能力ではなくコンテキストの不備であることが大半です。同じ指示でも、参照すべき仕様がどこにあるか分からなければ、エージェントは既存コードから推測します。推測は毎回違う結論になるので、出力が安定しません。
AI駆動開発では、この整備を3本柱のうちの1本として明示的に扱います。
| 柱 | 目的 | 主な中身 |
|---|---|---|
| ① ガードレール | AI出力の精度を上げる | 多層品質ゲート（静的解析→テスト→judge→CI） |
| ② コンテキスト整備 | AI出力の安定性を上げる | 正本ドキュメント群（L0〜L6）、参照優先順位 |
| ③ リファクタ／リポ統合 | AIが直しやすい構造にする | 複数リポの統合、境界の明確化 |
本記事は②を扱います。
最初に決めるべき1枚は「正本ルール」
整備を始める前に決めることが1つあります。
どのドキュメントが真実か。矛盾したとき、どれを優先するか。
これを「正本ルール」と呼びます。地味ですが、全レビューの合否基準の前提になります。
正本が決まっていないと、こうなります。
- レビュー指摘が「好み」に見えて、誰も従わない
- 古い仕様書と新しい実装のどちらに合わせるかで議論が再発する
- エージェントが矛盾する2つの文書を読んで、平均的に間違った実装を出す
正本ルールに書くべきことは3つです。
- 領域ごとの正本の所在（業務ルールはどこ、API仕様はどこ、画面仕様はどこ）
- 矛盾したときの優先順位
- 更新責任（誰が、どのタイミングで更新するか）
ドキュメントは3色に分けて管理する
作り方が根本的に違うので、種別を分けます。
| 種別 | 例 | 作り方 |
|---|---|---|
| 既存から抽出 | ER図、テーブル定義書、API定義書（OpenAPI） | AIに既存コードから生成させる |
| 新規作成 | PRD、ユースケース、画面↔APIマッピング、受け入れ基準 | 人＋AIで作る |
| ツール自動生成 | 依存グラフ、リポジトリ構造マップ | 決定論的スクリプトで生成 |
3番目を人やAIに書かせないでください。依存関係をAIに推測させると、それらしいが間違ったグラフが出ます。 これは「並列で何体エージェントを走らせられるか」を決める情報なので、不正確だと並列化そのものが壊れます。
L0〜L6 — 依存順に7階層で並べる
整備対象を依存順に階層化しておくと、抜け漏れと着手順が同時に分かります。上が基盤、下が運用寄りです。
| 層 | 内容 | 柱 |
|---|---|---|
| L0 コンテキスト基盤 | CLAUDE.md / AGENTS.md、リポジトリ構造マップ、ドメイン用語集 | ② |
| L1 既存資産の抽出物 | ER図、テーブル定義書、API定義書（OpenAPI） | ② |
| L2 プロダクト／要件 | PRD、画面一覧・ユースケース（Mock起点）、ユーザーフロー | ② |
| L3 設計 | デザイン仕様／トークン、フロント設計、シーケンス図、画面↔APIマッピング、拡張API仕様 | ② |
| L4 計画／実行 | 実装計画（タスク分解）、スキル／エージェント割り当て | ② |
| L5 品質／レビュー | テストケース、レビュー観点、受け入れ基準、Hooks設定、judgeルーブリック | ① |
| L6 運用／CI-CD | CI/CDチェック項目、デプロイ・運用手順 | ① |
L0 に書くこと
エージェントが最初に読むファイルです。分量を増やしすぎないのが要点で、次の5つに絞ります。
- 技術スタックとコーディング規約
- 使い回しルール（何を触ってよく、何を触ってはいけないか）
- ドメイン用語集への参照
- 正本の所在と参照優先順位
- 変更前に必ず確認させるファイル
L1 は「動く仕様書」
既存プロダクトの強みはここです。仕様書が古くても、コードは嘘をつきません。ER図・テーブル定義・API定義はコードから生成し、人が手書きしないのが原則です。手書きは初日から古くなります。
L2〜L3 は Mock を起点にする
新規に作る部分の要件は、Mockから逆算すると抜けが見えます。ユースケースを文章で書き切ってからMockを作ると、書き漏れが残るためです。詳しくは「Mock駆動開発のススメ」をご覧ください。
L3 の画面↔APIマッピング表は特に効きます。ユースケースとシーケンス図から必要なAPIを列挙し、既存API定義と突合して、不足が確定した分だけを拡張APIとして定義する。これをやらずに実装へ入ると、エージェントは存在しないAPIを前提にした実装を出してきます。
メタなドキュメントを1章分持つ
体系そのものに対する説明を別に持っておくと、運用が安定します。実案件では次の3本を独立した章にしています。
| ドキュメント | 中身 |
|---|---|
| AIに読ませる前提知識 | 正本一覧、参照優先順位、ドメイン／機能／モジュールの対応表 |
| AI実装ルール | 触らせない領域（DB・認可・課金）の指定、変更前に必ず確認させるファイル |
| AI生成コードのレビュー観点 | 生成物特有のチェック項目（既存パターンからの逸脱、過剰な抽象化など） |
これらは人間向けの開発ガイドとは別物です。読者がエージェントである文書として書きます。
進め方：全部揃えず「縦に1本」通す
最も多い失敗が、L0から順に全機能ぶんを揃えようとして力尽きるパターンです。正しくはこうです。
パイロット1機能について、L0 → L6 を縦に1本通す
L0 コンテキスト基盤
↓
L1 既存資産の抽出物
↓
L2 要件・Mock
↓
L3 設計
↓
L4 計画／実行
↓
L5 品質／レビュー
↓
L6 運用／CI-CD
↓
型が固まってから → 機能2・3・4… へ横展開
（以降はチケット単位の差分更新）
縦に1本通すと、体系の欠陥が実装で露出します。横に広げてから欠陥が見つかると、全機能ぶんを手直しすることになります。
そして横展開のフェーズでは、ドキュメントは「作る」ものから「更新される」ものに変わります。 チケットごとに影響範囲の差分を入れる運用に移行してください。この回し方は「チケットからマージまで」で扱います。
整備を高速化する「取得スキル」
機能ごとに毎回ゼロから調べていると、整備が実装に追い越されます。対象機能に関係するテーブル群・業務ルール・アルゴリズムを自動で集めてくる仕組み（スキルやサブエージェント）を先に作ると、以降の整備が高速かつ均質になります。
作り方は素朴で構いません。1機能ぶんを手で調べ、その手順をそのままスキルとして固定するだけです。均質になることのほうが、賢いことより価値があります。
よくある質問
Q. CLAUDE.md にはどれくらい書くべきですか？ A. 短いほうが機能します。長大な規約集を置くと、エージェントが重要な行を見落とします。詳細は個別ドキュメントに置き、L0からは参照させてください。目安として、規約本体ではなく「どこを見ればよいかの地図」を書きます。
Q. ドキュメントが実装に追い越されて腐ります。 A. 更新をマージ条件にしてください。PRのチェック項目に「影響したドキュメントを更新したか」を入れる、というレベルの運用で十分に機能します。整備を別プロジェクトとして走らせると必ず腐ります。
Q. ER図やAPI定義は自動生成で十分ですか？ A. 十分です。むしろ手書きより信頼できます。人間が読みやすい説明を足したい場合は、生成物とは別ファイルに置き、生成物を上書きしない構成にしてください。
Q. 用語集は本当に必要ですか？ A. 業務システムでは最優先です。「常勤」「稼働」「有効」といった語の解釈がずれると、エージェントは一貫して間違った実装を出します。しかも間違いが動いてしまうので発見が遅れます。
Q. どの層から着手すべきですか？ A. L0の正本ルールと用語集、次にL1の自動抽出です。この2つで「参照すべき真実」が確定し、以降の生成物の当たり率が大きく変わります。
関連サービス
最終確認日: 2026-07-25