AIプログラミングエージェントのための階層型ドキュメント体系の構築方法

プロジェクトの規模がある程度大きくなると、AIエージェントがコードを修正する際の最大の課題は「書けないこと」ではなく、「どのルールに従うべきか、どのファイルを修正すべきかがわからないこと」です。本記事では、実際の大規模プロジェクトで検証済みの階層型ナビゲーションnavigationドキュメント体系を紹介します。これにより、AIエージェントが自律的にコンテキストcontextを取得し、アーキテクチャarchitectureの制約を遵守し、クロスドメインの修正時にファイルを漏れなく変更できるようになります。

問題：AIエージェントのコンテキストcontext問題

大規模プロジェクトでAIプログラミングエージェント（GitHub Copilot、Claude、Cursor など）を使用する際によくある課題は次のとおりです：

• ルールの忘却：「特定の非同期asyncフレームワークを使え」と指示しても、別のファイルで禁止されている書き方をしてしまう
• 誤った箇所の修正：3つのモジュールを同時に修正する必要があるのに、1つしか変更しない
• ドメイン知識の欠如：初期化順序、イベントバスの規約convention、データフィールドの命名規則を理解していない
• 繰り返しの説明：新しい会話sessionを始めるたびに、プロジェクトアーキテクチャarchitectureを一から説明しなければならない

根本原因は次のとおりです：AIエージェントに構造化された、自律的に検索可能なプロジェクト知識ベースが存在しないこと。

私たちの解決策は、4層のドキュメント体系です：Constitution → Root Router → Domain Routers → Cookbook。さらに、AIエージェント自身の記憶memoryシステムを第5層とします。

第一層：Constitution — 憲法（絶対ルール）

ファイル：.github/copilot-instructions.md

これが体系の基盤です。いかなる状況でも違反してはならないグローバルな絶対ルールを定義します。

GitHub Copilot はこのファイルを自動的に毎回の会話sessionに注入します（GitHub のネイティブ機能です）。他のエージェント（Claude Code など）は起動時に手動で読み込む必要があります。

Constitution の内容はカテゴリ別に整理されています。以下は典型的な項目です（匿名化anonymized済み）：

## Async
- プロジェクト指定の非同期<ruby>フレームワーク<rt>framework</rt></ruby> mandatory — エンジン<ruby>ネイティブ<rt>native</rt></ruby>のコルーチンや Task.Run は禁止
- CancellationToken must be passed through all async call chains

## Data Integrity
- 数値範囲は必ず 0-100（0-1 ではない）
- DTO フィールド名は `id`、`entityId` ではない（AIエージェントが複数回誤認）

## Architecture Boundaries
- UI scripts only observe events — never contain business logic
- Systems communicate via event bus, not direct coupling

設計原則：

• 「何をしてはいけないか」だけを書く—ナビゲーションnavigationや具体的な実装には触れない
• 各ルールは実際のバグや手戻りに起因する— 「DTOフィールド名は id、entityId ではない」は、AIエージェントが何度もフィールド名を誤ったことが理由
• 形式は簡潔に— token制限内で完全に読み込めるようにする

Constitution は法律体系における憲法のようなものです。何をすべきかは教えませんが、絶対にやってはいけないことを明確に示します。

第二層：Root CLAUDE.md — プロジェクトルーターrouter

ファイル：プロジェクトルートの CLAUDE.md

Constitution が「法律」なら、Root CLAUDE.md は「地図」です。プロジェクトの全体像とタスク経路表routing tableを提供します：

## Task Routing — Where to Look

| If you're changing...                        | Read first                     |
|----------------------------------------------|--------------------------------|
| Core runtime flow (controllers, pipelines)   | src/core/CLAUDE.md             |
| AI/ML pipeline (prompts, guardrails)         | src/core/ai/CLAUDE.md          |
| UI framework, Views, Components              | src/ui/CLAUDE.md               |
| Entity behavior systems                      | src/core/entity/CLAUDE.md      |
| Cross-domain operations                      | docs/cookbook/                  |

AIエージェントはタスクを受け取ったら、まずこの表を確認し、どのドメイン文書documentを読むべきかを判断します。コードベース全体を盲目的に検索する必要はありません。

Root CLAUDE.md には以下も含まれます：

• プロジェクトの概要と中核的なビジネスサイクルcycleの説明
• 技術techスタックの早見表
• ディレクトリ構成図
• 主要なアーキテクチャarchitectureパターンの概要（イベント駆動、依存性注入dependency injection、インターフェースinterface分離など）

設計原則：ナビゲーションnavigationのみ、ルールは定義しない。 ルールはすべて Constitution にあります。Root は「どこを見るか」だけを伝えます。

第三層：Domain CLAUDE.md — ドメインルーターrouter

配置：主要なサブディレクトリごとに1つ、プロジェクト全体で18個。

これが体系の中核となる実働working層です。各ドメインルーターrouterには以下が含まれます：

3.1 親宣言declaration

> Parent: core/CLAUDE.md | Constitution: .github/copilot-instructions.md

各ファイルは自身の上位文書と最終的な権威の出典を明示的に宣言し、明確な参照連鎖を形成します。

3.2 ファイル役割表

そのディレクトリ内の各ファイルが何であるか、何をするかを列挙します：

## File Roles

| File                        | Role                                        |
|-----------------------------|---------------------------------------------|
| MainController.cs           | Turn orchestrator — Phase 1 → Phase 2       |
| InputGuardrail.cs           | Validates AI output within allowed bounds    |
| StreamFilter.cs             | Real-time stream filtering during generation |

これにより、AIエージェントは各ファイルのコードを読まなくても「どのファイルを修正すべきか」を判断できます。

3.3 初期化順序と依存制約constraint

## Initialization Order
Phase 1: AppConfig → SaveSystem → EntityRegistry
Phase 2: DataStore → AssetManager → StateTracker
...
Services can only Resolve<T>() systems registered in earlier phases.

3.4 サブドメイン経路routing

大規模なドメイン（Core など）はさらに下位に階層化されます：

core/CLAUDE.md
├── ai/CLAUDE.md         (AI/ML パイプライン)
├── narrative/CLAUDE.md  (ナラティブシステム)
├── world/CLAUDE.md      (ワールドシミュレーション)
├── data/CLAUDE.md       (データ管理)
├── entity/CLAUDE.md     (エンティティ動作)
└── services/CLAUDE.md   (外部サービス層)

ツリー状参照網network

すべての CLAUDE.md は参照木treeを形成します：

Constitution（絶対ルール、自動読み込み）
    ↓
Root CLAUDE.md（全体<ruby>経路<rt>routing</rt></ruby>）
    ├── core/CLAUDE.md → ai/ | narrative/ | world/ | data/ | entity/ | services/
    ├── ui/CLAUDE.md
    ├── models/CLAUDE.md
    ├── editor/CLAUDE.md → modules/ | data/ | tabs/
    └── data/CLAUDE.md

参照方向：

• 上方向：各ファイルが親 + Constitution を宣言
• 下方向：親が子ドメインを列挙
• 同階層：タスク経路表routing tableが兄弟ドメインを指す
• クロスドメイン：Cookbook を指す

設計原則：各 CLAUDE.md は自己完結型のコンテキストcontextパッケージである。 それを読めば、そのディレクトリ内で何ができて何ができないか、そして別のものを修正するにはどこへ行けばよいかがわかります。

第四層：Cookbook — クロスドメイン操作手順書

ディレクトリ：Docs/Cookbook/

最初の3層は「1つのドメイン内での修正方法」を解決します。しかし現実には、多くのタスクで複数ドメインを同時に修正する必要があります。たとえば：

• 新しい実行時runtimeサービスの追加 → DI登録、起動シーケンス、セーブシステム、場合によってはUIも修正が必要
• 新しいデータモデル型の追加 → モデル定義、インターフェースinterface、データ管理manager、UGCモード対応の修正が必要

Cookbook はこうした一般的な操作に対してステップ形式の確認checklistリストを提供します：

# Add New Service

## Steps
1. Create `MyService.cs` in `src/core/services/`
2. Implement `IInitializable`, `ISaveable` interfaces
3. Register in `AppBootstrap.InitPhase3()` — after TimeManager
4. Add save fields to `AppSaveData.cs`
5. Expose via `ServiceLocator.Register<IMyService>(instance)`
6. Add log tag `[MyService]` to Constitution

各Cookbookエントリには以下を記載します：

• 修正が必要なファイル（複数ドメインにまたがる）
• 修正の順序
• 遵守すべき制約（Constitution より）
• よくある落とし穴

設計原則：Cookbook は手順procedural知識であり、構造知識ではない。 Domain CLAUDE.md は「ここに何があるか」を教え、Cookbook は「この作業にはどのような手順processが必要か」を教えます。

第五層：AI記憶memoryシステム — 一時的と永続的

ドキュメント体系はプロジェクト知識の問題を解決しますが、AIエージェントには作業記憶memoryも必要です。エージェントが持つ記憶memory機構を3つのスコープscopeで活用します：

Session Memory は特に重要です。タスクを複数ステップで完了する必要がある場合、AIエージェントは Session Memory に「どこまで進んだか、何を発見したか、何が残っているか」を記録できるため、途中で中断interruptionされてもコンテキストcontextを復元できます。

実際のワークフロー

AIエージェントが「エンティティに新しい属性次元dimensionを追加する」というタスクを受け取った場合、完全なワークフローは次のようになります：

1. Constitution が自動読み込みされる
   → 理解：属性値は 0-100 でなければならない、変化量は -30 から +30

2. Root CLAUDE.md の<ruby>経路表<rt>routing table</rt></ruby>を確認
   → エンティティシステムの変更 → src/core/entity/CLAUDE.md を読む
   → データモデルの変更 → src/models/CLAUDE.md を読む
   → クロスドメイン操作 → docs/cookbook/ を確認

3. entity/CLAUDE.md を読む
   → ステートマシンはステートレス<ruby>パーサー<rt>parser</rt></ruby>であることを理解
   → ビヘイビア<ruby>パターン<rt>pattern</rt></ruby>は直接書き込めないことを理解

4. cookbook/Add-New-Model-Type.md を読む
   → ステップリストを取得：<ruby>インターフェース<rt>interface</rt></ruby>定義 → モデル作成 → 登録 → デュアルトラック対応

5. Session Memory に進捗を記録
   → "Step 1 done: interface defined"
   → "Step 2 in progress: creating model"

6. 完了後に Constitution を確認
   → すべての絶対ルールに違反していないことを確認

この一連の流れの中で、AIエージェントは人間の段階的な指示を必要とせず、またコードベース全体を運任せに検索する必要もありません。

設計の知見insights

なぜコード注釈commentではなく Markdown なのか？

コード注釈commentは局所的です。そのファイルを開いたときにしか見えません。しかしAIエージェントが必要とするのは、ファイルを開く前に、どのファイルを開くべきかを知ることです。CLAUDE.md が提供するのはメタ情報であり、個々のソースファイルの範囲を超えています。

なぜ1つの大きなドキュメントではなく階層構造なのか？

10,000行のドキュメントはAIのコンテキストcontextウィンドウを圧迫します。階層設計により、現在のタスクに関連するコンテキストcontextだけが読み込まれます—Constitution（約100行）+ Root（約150行）+ 1〜2つのDomain（各約100行）= 合計約500行であり、token予算budgetに十分収まります。

なぜ Constitution を .github/ 配下に置くのか？

GitHub Copilot は .github/copilot-instructions.md をネイティブに自動読み込みするためです。つまり、最も重要なルールが追加の操作なしに毎回の会話sessionに注入されます。他のエージェントも同様の機構（Claude Code の CLAUDE.md、Cursor の .cursorrules）で対応するファイルを自動読み込みできます。

各 Constitution ルールの背後には物語storyがある

私たちは「予防的に」ルールを追加することはありません。すべての絶対ルールは、実際のバグ、手戻り、あるいはAIエージェントの誤った出力に起因しています。たとえば：

• 「セーブデータ内の参照型リストはディープコピーすること」— シャローコピーが原因で微妙なセーブデータ破損が発生したため

CLAUDE.md という命名について

CLAUDE.md という名前はAnthropicのClaude Codeの規約conventionに由来します。Claude Code は作業ディレクトリ内の CLAUDE.md を自動的に読み込みます。しかし私たちの体系では、その役割は特定のAIツールを超えています。どんなAIエージェント（人間の開発者でさえも）がこのナビゲーションnavigation体系に沿って必要なコンテキストcontextを見つけられます。AGENTS.md、CONTEXT.md、あるいは任意の名前にも完全に置き換え可能です。肝心なのはファイル名ではなく、階層型ナビゲーションnavigationの構造そのものです。

まとめ

この体系の中核となる考え方は次のとおりです：AIエージェントを、入社研修orientationが必要な新しい同僚として扱うこと。 Constitution は就業company規則書、Root CLAUDE.md は組織organization図、Domain CLAUDE.md は部門ガイドguide、Cookbook は標準業務operating手順書（SOP）、Memory は個人のノートnotebookです。

これらの層が適切に連携すれば、AIエージェントはほぼ人間の介入interventionを必要とせずに、安全かつ正確に複雑なクロスドメインのコード修正を実行できます。