project-index

プロジェクトインデックス

AI エージェント向けに、プロジェクトのコンテキストとコードベースのドキュメントを生成します。

トリガー

• 初回セットアップ（「initialize」、「setup project index」、「index project」）→ initialize.md
• プロジェクトのコンテキスト（「overview」、「project context」、「refresh project」） → overview.md
• コードベースの概要（「map codebase」、「analyze codebase」、「summary」） → サブエージェントへのファンアウトを通じて、6 つのコードベース参照を並列に実行し、その後 出力をコンテキストとして review.md を実行します
• 差分更新（「refresh codebase」、「sync codebase」、「patch index」）→ refresh.md
• アーキテクチャ（単一ドキュメントの更新）→ architecture.md
• 規約（単一ドキュメントの更新）→ conventions.md
• テスト（単一ドキュメントの更新）→ testing.md
• インテグレーション（単一ドキュメントの更新）→ integrations.md
• チェックリスト（単一ドキュメントの更新）→ checklist.md
• ワークフロー（単一ドキュメントの更新）→ workflows.md
• 機能（単一ドキュメントの更新。垂直スライス型プロジェクトのみ）→ features.md
• 自己評価（ファンアウト後）→ review.md
• フィードバックの統合（「integrate feedback」、「sync knowledge」、 「integrate discoveries」）→ integrate-feedback.md
• マージポリシー（再実行時に各参照から読み込み）→ merge-policy.md

ワークフロー

initialize --> overview + (codebase fan-out + review when brownfield)
refresh    --> git diff range --> subset fan-out + review
                                     (fallback: full fan-out)

初回セットアップのエントリーポイントは initialize です。常に overview を実行します。プロジェクトがブラウンフィールド（ソースコードがある）の場合は、 コードベースのファンアウトを実行します。6 つのサブエージェント（アーキテクチャ、規約、テスト、インテグレーション、チェックリスト、 ワークフロー）を並列に実行し、垂直スライスが検出された場合は 7 つ目（features）も実行します。その後、メインエージェントが ファンアウトの出力をコンテキストとして review を実行します。

.agents/codebase/ が存在する場合は、より軽量な再実行経路として refresh を使用します。最後の同期マーカー以降の git の差分を確認し、変更されたパスを、該当領域に関係するサブエージェントに振り分けて、その対象のみを実行します。 ファイル数、マニフェストの変更、エントリーポイントの変更などのしきい値から大規模なリファクタリングが示される場合は、完全なファンアウトにフォールバックします。

コードベースのファンアウト

コードベース全体をマッピングする場合（ブラウンフィールドでの initialize、または「summary」トリガー）は、6 つのコードベース参照をすべて同じターン内で独立したサブエージェントとして実行します。7 つ目のサブエージェント（features）は、プロジェクトに垂直スライスが見られる場合にのみ実行されます（features.md の検出ゲートを参照）。

サブエージェント	読み取る内容	書き込む内容	条件
architecture	エントリーポイント、ディレクトリツリー、レイヤー境界	.agents/codebase/architecture.md	常に
conventions	代表的なソースファイル	.agents/codebase/conventions.md	常に
testing	テストファイル、テスト設定	.agents/codebase/testing.md	常に
integrations	API クライアント、DB モデル、環境ファイル	.agents/codebase/integrations.md	常に
checklist	スクリプト（package.json / Makefile）、コミット前設定	.agents/codebase/checklist.md	常に
workflows	トレースしたデータフローのエントリーポイント	.agents/codebase/workflows.md	常に
features	垂直スライスのディレクトリ、ルートのプレフィックス、同じ場所に配置されたテスト／ハンドラー／ビュー	.agents/codebase/features.md	垂直スライスが検出された場合

各サブエージェントは、それぞれの領域で必要なものだけを読み取ります。出力はディスクに保存されます — サブエージェントはコンテキスト経由で調査結果を返しません。

すべてのサブエージェントの完了後、メインエージェントはすべての出力をコンテキストとして review.md を実行します。レビューはサブエージェント間で分割できません — この統合はメインエージェントが担当します。

ガイドライン

• パターンを抽出する際は、一覧を確認するだけでなく実際のコードファイルを読みます
• 規定としてではなく、観察した規約を記録します
• 変わりやすい実装の詳細ではなく、安定したパターンやインターフェースに焦点を当てます
• 再実行時は既存のドキュメントを更新します（上書きせず、統合します）
• .agents/codebase/*.md は必要に応じて読み込まれ、常にコンテキストに含まれるわけではないため、内容を充実させます

アンチパターン：ソース境界の漏洩

.agents/codebase/*.md には、現在観察できる状態のみを記録します。 コードベースの事実を把握するための情報源として、.artifacts/（ブリーフ、PRD、設計ドキュメント、エピック、ロードマップ）を読んではいけません。(planned)、(TBD)、マイルストーンタグ、機能 ID、「feature X まで出荷済み」といった将来の内容は、コードベースマップではなく計画用アーティファクトに属します。.artifacts/ にモジュール、ルート、依存関係が記載されていても、現時点でファイルシステムに存在しないなら、それは存在しません。

アンチパターン：依存関係名から規約を決めつける

package.json に記載されている内容に基づいて規約を記録するのは、推測にすぎません。各ライブラリをプロジェクトがどのように利用し（拡張し、または上書きし）ているかを理解するため、実際の設定ファイルとソースコードを読みます。重要なのはフレームワークのデフォルト値ではなく、プロジェクトで実際に設定されている値です。