how

How

「X はどのように動作しますか？」という質問に答えるため、コードベースを調査します。サブシステムに新しく参加するシニアエンジニア向けに、明快なアーキテクチャの説明を作成します。注釈付きのソースコードではなく、実用的なメンタルモデルを構築するのに十分な説明を提供します。

次の 2 つのモードがあります。

1. Explain（デフォルト）。コードベースを調査して、明快に説明します
2. Critique。まず説明し、その後、複数のモデルを起動して、アーキテクチャ上の問題をそれぞれ独立して特定します

Explain モード

Step 1. 質問を理解し、複雑さを評価する

ユーザーが何について尋ねているのかを把握します。

• 「レートリミッターはどのように動作しますか？」、サブシステム
• 「オンデマンド利用の請求はどのように処理しますか？」、機能のフロー
• 「認証サービスはどのような構成ですか？」、アーキテクチャの概要
• 「ユーザーがフォームを送信したときに何が起きるのか、順を追って説明してください」、ランタイムのトレース

対象範囲を特定します。曖昧な場合は、調査を始める前に、最善と思われる解釈を示します。質問はしません。解釈が異なる場合は、ユーザーが修正できるようにします。

複雑さを評価して、進め方を決めます。

• 単純（単一のモジュール、小さなユーティリティ、「関数 X はどのように動作しますか？」のような限定的な質問）：エクスプローラーエージェントは起動せず、説明担当が一度の調査で説明します。Step 2b に進みます。
• 複雑（複数のファイルやサービスにまたがるサブシステム、横断的な機能、アーキテクチャ全体の概要）：まず並列でエクスプローラーエージェントを起動し、その後、説明担当に引き継ぎます。Step 2a に進みます。

判断に迷う場合は、単純なほうに寄せます。説明担当が行き詰まった場合は、いつでもエクスプローラーを起動できます。

Step 2a. 調査（複雑な質問のみ）

質問を 2〜4 個の並列調査の観点に分解します。それぞれがサブシステムの異なる側面を担当し、調査が重複しないようにします。「レートリミッターはどのように動作しますか？」の場合の分割例：

• エクスプローラー 1：データモデルと状態管理
• エクスプローラー 2：リクエスト経路と適用処理
• エクスプローラー 3：構成とメトリクスの基盤

適切な分解方法は質問によって異なります。判断して決めてください。限定的な質問なら、エクスプローラーは 2 つで十分です。広範なサブシステムなら、最大 4 つまで起動できます。

すべてのエクスプローラーを 1 つのメッセージで起動します。

• subagent_type：generalPurpose
• model：設定済みの how-explorer モデル（デフォルトは composer-2.5-fast）
• readonly：true

各エクスプローラーには、references/explorer-prompt.md の共通プロンプトに、担当する調査範囲を指定した指示を加えて渡します。各エクスプローラーは次のように進めます。

• 広く調べ始めます。関連ディレクトリを Glob し、主要な型、インターフェース、クラス名を Grep します
• 関連箇所をたどります。エントリーポイントから呼び出しチェーン（呼び出し元、呼び出し先、データフロー、型定義）を追跡します
• ファイル名から推測せず、実際のコードを読みます
• 入力から出力まで（またはトリガーから効果まで）の全経路を、曖昧な点なく説明できるところまで調査します
• 意外な点、分かりにくい点、新しく参加した人が誤解しそうな点を記録します

各エクスプローラーは、見つかったコンポーネント、追跡したフロー、読んだファイル、分かりにくい点を含む構造化された調査結果を返します。調査の重複は問題ありません。説明担当が結果を統合します。

続いて Step 3 に進みます。

Step 2b. 直接説明（単純な質問）

調査と説明を一度に行う Task サブエージェントを 1 つ起動します。

• subagent_type：generalPurpose
• model：設定済みの how-explainer モデル（デフォルトは claude-opus-4-8-thinking-xhigh）
• readonly：true

エージェントは独自に調査し（Glob、Grep、Read）、説明を直接作成します。説明の文体と出力形式については、references/explainer-prompt.md を参照してください。構成は同じですが、入力としてエクスプローラーの調査結果はありません。

Step 4 に進みます。

ステップ 3. 統合する（複雑な質問のみ）

すべての調査役からの結果が返ってきたら、単一の Task サブエージェントを起動し、調査結果を一貫性のある説明にまとめます。

• subagent_type: generalPurpose
• model: 設定済みの how-explainer モデル（デフォルトは claude-opus-4-8-thinking-xhigh）
• readonly: true

説明役はすべての調査役の結果を受け取り、人が読むための説明（以下の出力形式）を作成します。完全なプロンプトテンプレートについては、references/explainer-prompt.md を読んでください。説明役は、重複する調査結果を整理し、矛盾を解決して、各調査の断片を統一された全体像にまとめます。

ステップ 4. 提示する

説明役の出力をユーザーに提示します。明確にするための軽微な編集や、会話の文脈に基づく補足はできますが、大幅に書き換えてはいけません。説明役の伝達内容が成果物です。

出力形式

質問に合わせて、次の構成に従います。質問によっては、すべてのセクションが必要とは限りません。

概要。 1～2 段落で説明します。何であるか、何をするか、なぜ存在するかを述べます。読み進めるかどうかを判断できるだけの内容にします。

主要な概念。 重要な型、サービス、抽象化を説明します。それぞれを簡潔に定義します。網羅的に列挙するのではなく、残りの内容を理解するために必要なものに絞ります。

仕組み。 説明の中心となる部分です。処理の流れを順を追って説明します。何がきっかけとなり、何がどの順序で起き、データがどこへ渡されるのか、どのような判断が行われるのかを示します。疑似コードではなく、文章で説明します。読者が詳しく確認できるよう、具体的なファイルや関数を示します。ただし、本当に必要でない限り、コードブロックは載せません。

関連ファイルの場所。 関連するファイルやディレクトリの概要を示します。この領域の作業を始めるのに必要なものに絞り、すべてのファイルを列挙しないでください。

注意点。 気づきにくく、作業者がつまずきそうな点を説明します。見慣れない実装の理由となった歴史的背景や、既知の扱いづらい点も含めます。

批評モード

ユーザーが単なる理解ではなく、アーキテクチャ上の問題や改善点を求めた場合に有効になります。

ステップ 1. まず説明する

上記の説明フロー（ステップ 1～4）をすべて実行します。批評する前に、アーキテクチャを理解する必要があります。

ステップ 2. 批評役を起動する

説明が完成したら、設定済みの how-critics リストに含まれる各モデルにつき、アーキテクチャ批評役を 1 つずつ起動します（デフォルトは claude-opus-4-8-thinking-xhigh、gpt-5.5-high-fast、composer-2.5-fast）。すべてを 1 回のメッセージで起動します。

各批評役には、次を指定します。

• subagent_type: generalPurpose
• model: 設定済みの how-critics リストから選んだモデル。これらは最低限必要な推論能力を示します。アーキテクチャの分析にさらに深い検討が必要な場合は、リードがモデルを引き上げます。
• readonly: true

プロンプトテンプレートについては、references/critic-prompt.md を読んでください。各批評役には、次の内容を渡します。

1. ステップ 1 で作成した説明（再調査せずに済むようにするため）
2. 関連するファイルパス（実際のコードを確認できるようにするため）
3. references/critique-rubric.md に記載されたアーキテクチャ批評の評価基準

ステップ 3. リードが判断する

interrogate スキルと同じ枠組みを使います。リードは実務的な判断を下す役割であり、単に意見をまとめる役割ではありません。

調査結果を次のように分類します。

• 対応する。 すぐに修正する価値のあるアーキテクチャ上の問題
• 検討する。 実際の懸念点だが、費用対効果が明確でないもの
• 留意する。 妥当な指摘だが、優先度の低いもの
• 却下する。 誤り、文脈の欠落、または単なるスタイル上の好み

まず説明を提示し、その下に批評の結論を示します。説明だけでも独立して理解できるようにし、システムを理解したいだけの読者が批評に目を通さなければならない構成にしないでください。