コーディングエージェントにRAGは罠だった──設計文書を”検索”より”コンパイル”する Aegis MCP の使い方

Claude Codeを大規模プロジェクトで使うとき、設計文書・アーキテクチャガイドライン・ADR（Architecture Decision Record）などをどう渡すかが大きな課題になります。よく取られるのが「エージェントにfindやgrepで探させる」方法ですが、これは思った以上に問題があります。

この記事では、RAGではなくDAG（有向非巡回グラフ）の依存関係に基づいて設計文書を“コンパイル”して渡すアプローチと、それを実現するMCPツールAegisを紹介します。Laravelプロジェクト（17モジュール・140超のUseCase）での実測では、消費トークン12分の1・応答速度3.5倍を達成しています。

MCPの基礎はMCP完全ガイドを、大規模コードベースでの一般的な戦略は大規模コードベースガイドを参照してください。

コーディングエージェントのコンテキスト問題

AI開発が進むと、AGENTS.md・設計書・仕様書・ADRといった文書が増えていきます。エージェントはコードを書く前にこれらを参照すべきですが、現状は以下の問題が起きがちです。

特にRAGの問題は、「UseCase を実装するときに必要なガイドライン」を「UseCase」という単語で検索しても、本当に必要な文書に辿り着けないことです。設計意図は命名規則やUseCase命名に含まれているとは限りません。

「検索」ではなく「コンパイル」という発想転換

Aegisの基本アイデアはシンプルです。「どのファイルを編集するか」がわかれば、「そのファイルを正しく書くために必要な文書」も事前に定義できるという考え方です。

たとえばapp/UseCases/配下のファイルを編集するなら：

• usecase_guidelines.md（UseCase実装のガイドライン）
• entity_guidelines.md（UseCaseが依存するEntityのルール）
• exception_guidelines.md（例外処理方針）

この「usecase_guidelines.mdはさらにentity_guidelines.mdとexception_guidelines.mdに依存する」という関係をDAG（有向非巡回グラフ）として定義し、ファイルパスを渡すだけで必要な文書群を芋づる式に取得できます。

実測パフォーマンス比較

Laravelプロジェクト（17モジュール・140超のUseCase）で「UseCase を実装する上での注意点は？」という同じ質問をClaude Codeに投げた結果です。

数値の改善だけでなく、設計意図（ADR）まで届く回答品質の向上が大きなポイントです。コスト管理の観点はコスト管理完全ガイドも参照してください。

AegisのDAGアーキテクチャ

Aegisは内部でSQLiteにドキュメントとファイルの依存関係を保持し、再帰CTE（Common Table Expressions）で依存を解決します。

4段階のルーティングで必要な文書を決定します：

1. パスマッチング：グロブパターンでターゲットファイルと照合
2. レイヤー解決：ファイルパスからアーキテクチャレイヤーを推論
3. コマンド依存：scaffold/refactor/reviewなど操作タイプ別の依存を処理
4. 推移閉包：doc_depends_onエッジを再帰的にたどる

重要な設計原則としてAgent Surface（読み取り専用）とAdmin Surface（管理専用）の完全分離があります。エージェントは知識ベースを直接変更できず、変更は人間が承認して初めて反映されます。

Claude Codeへの導入手順

ステップ1：MCPサーバーを追加する

# Agent サーフェス（読み取り専用・エージェント用）
claude mcp add aegis -- npx -y @fuwasegu/aegis --surface agent

# Admin サーフェス（管理用・ドキュメント登録や提案承認に使う）
claude mcp add aegis-admin -- npx -y @fuwasegu/aegis --surface admin

ステップ2：プロジェクトを初期化する

# プロジェクトをスキャンして初期化状態を検出
aegis_init_detect

# 検出結果を確認して初期化
aegis_init_confirm

ステップ3：IDE固有のアダプタを生成する

npx @fuwasegu/aegis deploy-adapters
# → CLAUDE.md に Aegis 使用指示が追記される
# → .aegis/aegis.db (SQLite) が作成される

ステップ4：設計文書をインポートする

Admin Surfaceから設計文書を取り込み、ファイルパスとの対応関係を定義します。

# aegis-admin ツールとして呼び出す
aegis_import_doc({
  "path": "docs/usecase_guidelines.md",
  "layer": "application",
  "glob_patterns": ["app/UseCases/**/*.php"]
})

# 依存関係の定義（usecase_guidelinesはentity_guidelinesに依存）
aegis_import_doc({
  "path": "docs/entity_guidelines.md",
  "layer": "domain"
})

使い方：aegis_compile_contextで文書を取得する

セットアップが完了したら、コードを書く前にaegis_compile_contextを呼ぶだけです。CLAUDE.mdにdeploy-adaptersで指示が追記されるため、以後Claude Codeは自動的にこのツールを呼ぶようになります。

# 編集予定のファイルを渡すと、必要な設計文書を返す
aegis_compile_context({
  "target_files": [
    "app/UseCases/Order/CreateOrderUseCase.php"
  ],
  "command": "scaffold",
  "plan": "注文作成のUseCaseを新規実装する"
})

# → usecase_guidelines.md
# → entity_guidelines.md（UseCaseが依存するEntityのルール）
# → exception_guidelines.md（例外処理方針）
# が自動的に返ってくる

引数のcommandはscaffold・refactor・review・bugfixなど操作タイプで、コマンドによって異なる依存文書が返ります。planは自然言語の実装予定説明で、より精度の高い文書選択に使われます。

Observationサイクル──エージェントが知識ベースを育てる

Aegisには「エージェントが自分で知識ベースの改善提案をできる」仕組みがあります。ただし、知識ベースへの書き込み権限はエージェントに与えず、人間の承認が必須です。

# ステップ1: エージェントがコードを書いたあとにセルフレビュー
# 「entity_guidelinesが足りなかった」と判断したら観察を記録
aegis_observe({
  "event_type": "compile_miss",
  "related_compile_id": "compile_abc123",
  "payload": {
    "missing": "entity_guidelines.md",
    "context": "Entityの不変条件チェックを見落とした"
  }
})

# ステップ2: 観察から提案を生成（Admin Surface）
aegis_process_observations()
# → Proposal が生成される

# ステップ3: 人間が提案を確認・承認
aegis_list_proposals()   # 提案一覧を確認
aegis_approve_proposal({ "proposal_id": "prop_xyz" })  # 承認
# → 知識ベースに反映される

このサイクルにより、使い続けるほどAegisの知識ベースが精度を増していきます。「エージェントが学習を提案し、人間が承認する」という人間起点のフィードバックループが設計の核心です。

どんなプロジェクトに向いているか

AegisはClaude Code・Cursor・Codexの3つに対応しています。チームで複数のAIエージェントを使い、かつ設計文書を一貫して参照させたいケースで特に効果を発揮します。

コンテキスト設計の全体論はコンテキストエンジニアリングガイドも参照してください。

よくある質問