how

仕組み

コードベースを調べ、「X はどのように動作しますか？」という質問に答えます。サブシステムに参加するシニアエンジニア向けのアーキテクチャ説明として、実用的な全体像を把握するのに十分な詳しさで説明します。ただし、ソースコードに注釈を付けたような説明にはしません。

起動するエージェントはすべて、読み取り専用の general-purpose サブエージェントです。調査エージェントは pstack のモデル設定にある how explorer の行（デフォルトは sonnet）を使用し、説明エージェントは how explainer の行（デフォルトは opus）を使用します。Skill ツールで pstack-harness を呼び出し、各起動のモデル、処理量、エージェントタイプを解決してください。その Spawn a role セクションには、設定がない場合、inherit-parent、拒否された値についても説明されています。

1. 複雑さを評価する

対象範囲が曖昧な場合は、解釈を示したうえで調査します。ユーザーは必要に応じて方向を修正できます。

• シンプル（単一のモジュール、小さなユーティリティ、「関数 X はどのように動作しますか？」のような限定的な質問）：調査エージェントは起動しません。references/explainer-prompt.md をもとに、直接調査の指示を加えて説明エージェントを 1 つ起動し、調査と説明を 1 回で行います。「調査結果」と「統合」の項目は省略します。手順 4 に進みます。
• 複雑（複数のファイルやサービスにまたがるサブシステム、横断的な機能、アーキテクチャ全体の概要）：手順 2 に進みます。

判断に迷った場合は、シンプルな方法を選んでください。

リポジトリに GitNexus インデックス（.gitnexus/ が存在）があり、gitnexus が PATH にある場合は、最初にインデックスを更新します。何かを起動する前に、自分で gitnexus analyze --index-only を 1 回実行してください（インクリメンタル処理のため、最新の場合は何も行いません。並列処理の各アームから実行してはいけません）。その後、調査の手がかりを得ます。実行フローには gitnexus query "<concept>"、呼び出し元と呼び出し先には gitnexus context <symbol>、2 つのシンボル間の経路には gitnexus trace <from> <to> を使います。グラフの結果は読むべき箇所を選ぶために使いますが、信頼できる情報源はあくまでコードです。インデックスが反映するのは最後に解析されたコミットであり、未コミットの変更は反映されません。インデックスまたは CLI がない場合は、通常どおり調査してください。リポジトリにインデックスがなく、gitnexus が PATH にある場合は、再度調査する価値のあるリポジトリについて、複雑な質問に回答した後で、ユーザーに gitnexus analyze の実行を 1 度提案してもかまいません。

2. 調査（複雑な場合のみ）

質問を 2～4 個の観点に分解します。それぞれ、サブシステムの異なる側面を扱うものにします。各観点を記入した references/explorer-prompt.md を使って、すべての調査エージェントを 1 回のメッセージで起動します。

3. 統合（複雑な場合のみ）

すべての調査エージェントから結果が返ったら、各エージェントの調査結果と、記入済みの統合指示を含めた references/explainer-prompt.md を使って説明エージェントを 1 つ起動します。直接調査の指示は省略します。

4. 提示

説明エージェントの出力を提示します。明確さや会話の文脈に合わせて軽く編集してもかまいません。大幅に書き換えてはいけません。

出力形式

説明には references/explainer-prompt.md で定められたセクションを使い、該当しないセクションは省略します。セクションは「概要」「主要な概念」「仕組み」「関連ファイル」「注意点」です。