researching-codebases

コードベースの調査

並列のサブエージェントを連携させて、複雑なコードベースに関する質問に回答します。

使用する場面

• 複数のファイルやコンポーネントにまたがる質問
• コードをたどって調べる必要がある「X はどのように動作しますか？」という質問
• コードベース全体からパターンや例を見つける場合
• アーキテクチャ上の判断やデータフローを理解する場合

使用しない場面

• 単純な「X はどこにありますか？」という質問：code-locator を直接使用してください
• 単一ファイルに関する質問：ファイルを読むだけで十分です
• 外部やウェブのみを対象とした調査：web-searcher を直接使用してください

ワークフロー

0. 過去の調査を確認する（任意）

新しい調査の質問を分解する前に、関連する過去の調査を確認することを検討してください。

1. list-research.py スクリプトを実行して、最近の調査ドキュメントを確認します
2. search-research.py スクリプトを関連キーワードで実行します
3. 関連する調査が見つかった場合は、read-research.py スクリプトを実行して読み込みます
4. 最初から始めるのではなく、過去の調査結果を活用します

スクリプトの使用方法については、research-tools.md を参照してください。

1. まず、言及されたファイルを読む

ユーザーが特定のファイルを挙げている場合は、エージェントを起動する前に、そのファイルを最後まで読んでください。分解に必要なコンテキストを把握できます。

2. 質問を分解する

クエリを並列で実行する調査タスクに分割します。以下の点を検討してください。

• コードベースのどの領域が関連しますか？
• 場所の特定、分析、例のうち、どれが必要ですか？
• エージェントの機能については、agent-selection.md を参照してください

3. 並列エージェントを起動する

独立したタスクについては、複数のエージェントを同時に起動します。適切な subagent_type を指定して task ツールを使用してください。

統合する前に、すべてのエージェントの完了を待ってください。

4. 結果を統合して回答する

調査結果をまとめ、一貫性のある回答にします。

• 質問への直接的な回答
• 重要な file:line 参照
• コンポーネント間のつながり
• さらに調査が必要な領域がある場合は、未解決の質問

5. 保存を提案する（任意）

本格的な調査の場合は、次のように尋ねます。

これを調査ドキュメントに保存しますか？（プロジェクト：.research/ またはグローバル：~/.research/）

簡単な回答の場合は省略します。

保存する場合：

1. gather-metadata.py スクリプトを実行して、日付、リポジトリ、ブランチ、コミット、作業ディレクトリを取得します。
2. クエリ（ユーザーの質問から）とタグ（内容から）を追加します
3. output-format.md に従って YAML フロントマターを記述します
4. ディレクトリが存在しない場合は作成します
5. ファイル名には {filename_date}_topic-slug.md を使用します

エージェントリファレンス

各エージェントを使用する場面については、agent-selection.md を参照してください。

よくある間違い

コンテキストを読む前にエージェントを起動する： ユーザーが言及したファイルは、必ず先に読んでください。

すべてのエージェントの完了を待たない： すべてのエージェントの完了後にのみ、結果を統合してください。

簡単な回答を過度に文書化する： すべての質問について、調査ドキュメントを保存する必要があるわけではありません。

並列で進められるタスクを逐次実行する： タスクが独立している場合は、まとめて起動してください。