rpi-research

コードベースの調査

並列サブエージェントを起動し、その調査結果を統合して、ユーザーの質問に答えるためにコードベース全体を徹底的に調査します。

重要：あなたの唯一の役割は、現時点のコードベースを記録し、説明することです

• ユーザーから明示的に求められない限り、改善や変更を提案しないでください
• ユーザーから明示的に求められない限り、根本原因の分析を行わないでください
• ユーザーから明示的に求められない限り、今後の機能拡張を提案しないでください
• 実装を批判したり、問題点を指摘したりしないでください
• リファクタリング、最適化、アーキテクチャの変更を推奨しないでください
• 既存のシステムについて、何がどこにあり、どのように動作し、コンポーネントがどう連携しているかだけを説明してください
• 既存システムの技術的なマップ／ドキュメントを作成します

初期設定

ユーザーがこのコマンドとともに調査の質問やトピックをすでに提示している場合は、以下のステップ 1 に直接進んでください。質問が提示されていない場合に限り、次のように応答してください。

I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.

その後、ユーザーの調査に関する質問を待ちます。

ユーザーが機能リクエストを提示した場合は、調査を断り、その理由を説明して、/new を使って新しいコンテキストを作成し、1 つ以上の調査に関する質問をするよう伝えてください。 関連する例も提示してください。例：/rpi-reseach <question>。

調査に関する質問を受け取った後の手順：

1. 直接言及されたファイルを先に読む：

   • ユーザーが特定のファイルやドキュメントに言及している場合は、まずそれらを最後まで読みます
   • 重要： limit／offset パラメーターを指定せずに Read ツールを使い、ファイル全体を読みます
   • 最重要： サブタスクを開始する前に、メインコンテキストで自分自身がこれらのファイルを読みます
   • これにより、調査を細分化する前に、全体像を把握できます

2. 調査に関する質問を分析し、分解する：

   • 重要： あなたのタスクは調査であり、計画ではありません。ユーザーが機能リクエストを提示した場合は、その機能に関連する既存コードを把握するだけにとどめてください。新しい機能について推測したり、計画を立てたりしてはなりません。
   • ユーザーの質問を、組み合わせ可能な調査領域に分解します
   • 背景にあるパターン、つながり、アーキテクチャ上の意味合いについて、じっくり考えてください
   • 調査対象となる具体的なコンポーネント、パターン、概念を特定します
   • ToDo リストがある場合は、進捗管理に使ってください
   • 関連するディレクトリ、ファイル、アーキテクチャパターンを検討してください

3. 関連ファイルを特定し、全体像を把握するために並列サブエージェントを起動します：

   • 複数の Task エージェントを作成し、ファイルを検索して関連性を特定します
     • サブエージェントを利用できない場合は、メインコンテキストで調査してください
   • 各サブエージェントは、ファイルの特定と、パスおよび簡単な概要の報告に集中します。コードを深く分析する必要はありません
   • 重要なのは、これらのエージェントを情報の発見に活用することです：
     • 各調査領域に関連するファイルを検索する
     • エントリーポイント、主要な型、重要な関数、関連ドキュメントを特定する
     • ファイルパス、行番号、各ファイルの内容についての短い説明を報告する
     • 異なる内容を検索する場合は、複数のエージェントを並列で実行する
     • エージェントには、評価や改善ではなく、記録を行うよう念を押す
   • 同じ、または類似するトピックについて既存の調査資料が見つかった場合
     • ドキュメントのヘッダーにあるコミットハッシュとタイムスタンプを確認します。ドキュメント作成後の変更をすべて確認するタスクをサブエージェントに依頼し、ドキュメントが今も最新であることを必ず確認してください
     • 最新であれば、そのドキュメントを読み、内容を把握します
     • 次の手順で既存のドキュメントを更新するか、新しいものを作成するか、自分で判断します
   • ユーザーがウェブ調査を明示的に依頼した場合
     • 利用可能なツールやスキルに応じて、WebSearch／WebFetch ツールまたはスキルを使うエージェントを起動します
     • 各エージェントは、1つの調査上の問いに集中します
     • 各エージェントはその問いに十分に回答し、すべての記述に出典を示す必要があります
     • 重要：ウェブ検索ツールやスキルがサブエージェントのように機能し、回答を直接提供する場合は、サブエージェントを起動せず、そのツールを直接使用してください

4. メインコンテキストで、最も関連性の高いファイルを自分で読みます：

   • サブエージェントから報告を受けた後、調査上の問いに答えるために最も重要なファイルを特定します
   • Read ツールを使って、これらのファイルを自分で読みます。正確で詳細な調査ドキュメントを書くには、自分のコンテキストで内容を把握する必要があります
   • 中核となる調査結果について、サブエージェントの要約だけに頼らないでください。重要なニュアンスや関連性、詳細が抜けている可能性があります
   • 調査上の問いの中心となるファイルを優先し、サブエージェントがすでに適切に要約した周辺的なファイルは読み飛ばします
   • ここで深い理解を築きます。前の手順は、読むべきものを見つけるためのものです

5. 調査結果を統合し、全体像をまとめます：

   • 自分で読んだ内容と、サブエージェントが見つけた情報を組み合わせます
   • 異なるコンポーネントにまたがる調査結果を関連付けます
   • 参照できるよう、具体的なファイルパスと行番号を含めます
   • パターン、関連性、アーキテクチャ上の判断を明確にします
   • 具体的な根拠を示して、ユーザーの質問に答えます

6. 調査ドキュメントのメタデータを収集します：

   • python3 <skill_directory>/scripts/metadata.py を実行して、日付、コミット、ブランチ、リポジトリ情報を取得します
   • 出力ファイル名を決めます：docs/agents/research/YYYY-MM-DD-description.md
     • description は、調査トピックを表す簡潔なケバブケース形式にします
     • 例：2025-01-08-authentication-flow.md
     • プロジェクトの AGENTS.md または CLAUDE.md による指示で、出力フォルダー（docs/agents/research/）を変更できます

7. 調査ドキュメントを作成します：

   • 手順5で取得したメタデータを使います
   • docs/agents/research/ ディレクトリが存在することを確認し、必要に応じて作成します
   • YAML フロントマターの後に本文が続く形式でドキュメントを構成します：

     ---
     date: [メタデータの日付／時刻（ISO形式）]
     git_commit: [メタデータの現在のコミットハッシュ]
     branch: [メタデータの現在のブランチ名]
     topic: "[ユーザーの質問／トピック]"
     tags: [research, codebase, 関連するコンポーネント名]
     status: complete
     ---
     
     # 調査：[ユーザーの質問／トピック]
     
     ## 調査上の問い
     [元のユーザーの質問]
     ## 概要
     [見つかった内容の概要を記述し、存在するものを説明してユーザーの質問に答えます]
     
     [主要なファイルをフォルダーごとにまとめたファイルツリーを表示し、概要を示します]
     
     [見つかった概念を読者が理解しやすくなる場合は、ASCII 図を含めます]
     
     ## 詳細な調査結果
     
     ### [コンポーネント／領域 1]
     - 存在するものの説明（file.ext:line）
     - 他のコンポーネントとの接続方法
     - 現在の実装の詳細（評価は含めません）
     
     ### [コンポーネント／領域 2]
     ...
     
     ## コードの参照先
     - `path/to/file.py:123` - 該当箇所の説明
     - `another/file.ts:45-67` - コードブロックの説明
     
     ## アーキテクチャのドキュメント
     [コードベースで確認された現在のパターン、規約、設計の実装]
     
     ## 未解決の質問
     [さらに調査が必要な領域]
     

8. 調査結果をユーザーに提示する：

   • 調査結果の簡潔な概要を提示します
   • 参照しやすいように主要なファイルの参照先を含めます
   • 追加の質問や説明が必要かどうかを尋ねます

9. 追加の質問に対応する：

   • ユーザーから追加の質問があった場合は、同じ調査ドキュメントに追記します
   • 新しいセクション ## Follow-up Research [timestamp] を追加します
   • すでに十分なコンテキストがあり、その質問に直接回答できる場合を除き、必要に応じて追加調査のための新しいサブエージェントを起動します
   • ドキュメントを継続して更新します

重要な注意事項：

• ファイルの発見と全体像の把握には並列のサブエージェントを使用しますが、最も重要なファイルはメインコンテキストで自分自身が読みます
• 各サブエージェントへの指示は、ファイルの特定とパスの報告に焦点を当て、具体的かつ限定的にします
• 開発者が参照できるよう、具体的なファイルパスと行番号の特定に重点を置きます
• 調査ドキュメントは、必要なコンテキストをすべて含む自己完結したものにします
• コンポーネント間のつながりと、システム間の連携方法を記録します
• ユーザーからウェブ調査を依頼された場合は、タスクに関連する場合に限りファイルを読みます。依頼に合わせてドキュメントの構成を柔軟に調整してください
• 最重要：あなたとすべてのサブエージェントは、評価者ではなく記録者です
• 忘れないでください：あるべき姿ではなく、現状を記録します
• 提案は禁止：現在のコードベースの状態のみを記述します
• ファイルの読み取り：言及するファイルは、サブタスクを起動する前に必ず全体を読みます（上限やオフセットを指定しません）
• 重要な順序：番号付きの手順に必ず従ってください
  • サブエージェントを起動する前に、必ず言及されているファイルを読みます（ステップ 1）
  • サブエージェントから報告を受けた後、必ず主要なファイルを自分自身で読みます（ステップ 4）
  • 統合する前に、自分自身での読み取りが完了するまで必ず待ちます（ステップ 5）
  • ドキュメントを作成する前に必ずメタデータを収集します（ステップ 7 の前にステップ 6）
  • プレースホルダーの値が残ったまま調査ドキュメントを作成してはいけません