why

Why

コードの背後にある動機や意図を調査します。対応する how スキルでは、コードが何をするのか、どのように動作するのかを解説します。why では、そのコードが現在の形になった要因を明らかにします。

ディスパッチの契約。 設定されたすべてのロールを provider-dispatch.md を通じて解決してください。調査担当には親のライブ MCP サーフェスが必要です。そのため、既定かつ推奨されるポータブルなルートは inherit-parent（またはそのエイリアス auto）です。コードアンカーはパスで渡してください。Codex では、残りの Claude ツール名を codex-tools.md を通じて解決してください。各サブエージェントに割り当てる作業量は、poteto-mode スキルの「Subagents」セクションに従って選んでください。

すべてのレーンで MCP アクセスを維持してください。MCP アクセスを取り除くサブエージェントの種類や実行モードは選ばないでください。そうすると、MCP を利用する調査担当と、統合担当による引用のスポットチェックが無効になります。調査担当は、引き続き何も書き込まないでください。

Operating Posture

慎重で、注意深く、正確な調査担当者として行動してください。把握していることと推測していることを正直に区別してください。信頼度の枠組みと表現ガイドの全体については、references/epistemics.md を読んでください。統合担当はこれに従う必要があります。

Step 1. Understand the Target and the Question

対象は通常、コードの一部、パターン、機能、または名前の付いた設計上の決定事項です。質問は通常、設計上の根拠、トレードオフ、動機となったエッジケース、外部制約、不要なコード、または広範な履歴調査に関するものです。

対象が曖昧な場合（明確な参照先のない「なぜこの方法にしているのか？」など）は、会話の文脈（開いているファイル、最近の編集、カーソル位置、直前の話題）から最善の推測をしてください。解釈が違っていればユーザーが修正できるよう、解釈を簡潔に伝えてから作業を進めてください。

Step 2. Establish the Code Anchor

調査担当を起動する前に、シードコンテキストをインラインで作成してください。ファイルパスと行範囲、主要なシンボル（関数、クラス、定数）、対象に触れた直近のコミット、マージコミットの PR 番号（件名の (#1234) パターン）、関連するチケット ID を含めます。最終変更コミットには git blame -L <start>,<end> <file> を実行し、名前変更を含むパッチ付きの全履歴には git log --follow -p -- <file> を実行してください。PR 番号が見える直近のコミットには git log --oneline -20 -- <file> を実行し、PR 番号の抽出には git log -1 --format=%B <commit> を実行してください。次に、内容のあるコミットについて PR の本文と議論を取得します。コマンドは gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews です。このアンカーをすべての調査担当と統合担当に渡してください。

Step 3. Spawn Parallel Investigators

既定では、並列調査を全面的に実施してください。 目標は網羅的なカバレッジマップを作成することであり、最小限にとどめることではありません。該当なしという結果も記録し、検索を省略しないでください。

ディスカバリー

調査担当者を起動する前に、Claude Code 環境で利用可能な MCP を一覧表示します。システムプロンプトの先頭にあるツール一覧を使用してください（各 MCP は mcp__<server>__<name> というプレフィックスのツールとして表示されます）。それ以外の場合は、プラグインまたはプロジェクト内の .mcp.json を読み込むか、claude mcp list を実行します。

利用可能な各 MCP を、次の証拠カテゴリのいずれかに割り当てます。

1. ソース管理の履歴
2. 課題／チケット管理
3. 長文ドキュメント
4. リアルタイムのチームチャット
5. インフラストラクチャのオブザーバビリティ
6. エラー／例外トラッキング
7. プロダクト分析ウェアハウス

ソース管理は git と gh で常に利用できます。残りの6カテゴリについては、MCP 名、サーバーの指示、ツール名、リソース記述子に基づいて分類します。複数のカテゴリに当てはまる可能性がある MCP は、主な証拠に一致するカテゴリを選びます。曖昧なケースはカバレッジマップに記録します。

該当する MCP があるカテゴリごとに調査担当者を1人ずつ、すべて同じファンアウトフェーズで起動し、並行して実行します。各担当者が所有するツールまたは MCP は1つだけです。1人のエージェントに複数の MCP を担当させないでください。担当する MCP を利用可能にしたうえで、各担当者を why investigators, synthesizer 記述子（デフォルトは inherit-parent）経由でルーティングします。調査担当者はファイルを書き込みません。これは、MCP 対応の実行モードが機械的に読み取り専用でない場合も同様です。

各調査担当者へのプロンプトは、内容を埋めた references/investigator-prompt.md と、以下の項目で構成します。

• 選択した MCP 用のカテゴリ別プレイブック references/sources/<source>.md。references/source-playbook.md の例を参考にして調整します。
• 対象コードが防御的な処理に見える場合は、references/sources/incident-postmortem.md（null チェック、再試行ロジック、タイムアウト処理、レート制限、フィーチャーフラグ、エグレスガード、OOM ハンドラーなど）
• コードアンカーとユーザーの元の質問

調査担当者の割り当て：利用可能な証拠カテゴリごとに1人

以下の各カテゴリは、「特に得意なこと」に示す、「なぜ」の異なる側面を明らかにするのに独自の強みがあります。これを参考に、各カテゴリから何が得られるかを把握し、結果が空だった場合は不足を記し、証明可能なほど無関係なまれなケースに限り、スキップする理由を示します。

1. ソース管理（git の履歴、PR 用の gh、コードコメント、テスト）。必ず起動します。唯一、常に利用が保証されている情報源です。特に得意なのは、レビュー時に記録された実装上の理由です。
2. 課題／チケット管理（Linear、Jira、GitHub Issues、Plane、Shortcut MCP など）。特に得意なのは、プロダクトまたはビジネス上の推進要因です。エンジニアリングの外部に理由がある場合に最も強みを発揮します。
3. 長文ドキュメント（Notion、Confluence、Google Docs、Coda MCP など）。特に得意なのは、コードになる前に書き残された、長文の設計上の理由です。
4. リアルタイムのチームチャット（Slack、Discord、Microsoft Teams、Mattermost MCP など）。特に得意なのは、文書には残らなかったリアルタイムの議論です。ソース管理、チケット、ドキュメントに残る記録が少ない場合は、特に重要です。
5. インフラストラクチャのオブザーバビリティ（Datadog、New Relic、Honeycomb、Grafana、Splunk MCP など）。特に得意なのは、コードの動機となったインフラストラクチャや実行時の実情です。対象がインフラのシグナル（タイムアウト、再試行、レート制限、サーキットブレーカー）に対応する場合に、最も強みを発揮します。
6. エラー／例外トラッキング（Sentry、Rollbar、Bugsnag、Airbrake MCP など）。特に得意なのは、防御的なコードや修正コードの動機となった、具体的な例外とエラーの経緯です。catch ブロック、null ガード、型チェック、再試行、その他の防御処理に最も強みを発揮します。
7. プロダクト分析ウェアハウス（Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP など）。特に得意なのは、コードを形作ったプロダクトやデータの実情です。フィーチャーフラグで制御されるコード、実験に基づくリリース、データ移行、「この数値はどこから来たのか」という質問に最も強みを発揮します。

調査担当を省略する場合

省略するのは、最終的な「参照した情報源」に明示的かつ書面による根拠を記載する場合に限ります。有効な理由は次の2つです。

• この環境では、そのカテゴリに該当する MCP が利用できない。これは選択ではなく、ギャップとして明記します。「リアルタイムのチームチャットは調査対象外です。該当する MCP が利用できないため、会話記録を検索できませんでした。」
• 情報源が単に「おそらく無関係」なのではなく、明らかに無関係であると証明できる。判断のハードルは高く設定します。「エラー／例外追跡は調査対象外です。対象はビルド時のスクリプトであり、実行時にコードが実行される経路がないためです。」

スコープの評価から、PR の説明にすでに完全な回答が記載されている、単一コミットの単純な対象だと思われる場合は、利用可能な7つのカテゴリ検索がすべて冗長になることを確認した後に限り、インラインで回答してもかまいません。その旨を明示してください。このケースはまれです。

ステップ 4. 統合する

why investigators, synthesizer ディスクリプター（デフォルトは inherit-parent）を通じて、統合担当を1人割り当てます。統合担当が引用をスポットチェックする品質確認を行うため、関連する MCP へのアクセスを維持してください。統合担当はファイルを書き込みません。次の情報を渡します。

1. 調査担当の調査結果。null の結果や、根拠を添えて省略したカテゴリも含めます
2. コードのアンカー
3. ユーザーの元の質問
4. references/epistemics.md に記載された認識論のフレームワーク
5. references/synthesizer-prompt.md に記載された統合担当向けプロンプトのテンプレート

ステップ 5. 提示する

統合担当の出力をユーザーに提示します。明確さのための軽微な編集や、会話の文脈からの補足は可能ですが、確信度を示す表現は書き換えないでください。

出力形式

構成は references/synthesizer-prompt.md に記載されたものを使用します。「質問」「対象のコード」「調査結果」「妥当に推論できること」「対立する仮説」「不明な点」「参照した情報源」「確信度の要約」です。必要に応じて調整してかまいませんが、確信度の区別は保ち、「参照した情報源」は、何も見つからなかった調査担当や、省略した調査担当も含め、担当者ごとに1行で記載し、省略した場合はその理由も明記してください。

ユーザーの「why」に関する質問が、このコードを変更する前段階の質問である場合は、「参照した情報源」の後に、変更計画の制約として、系譜調査の結果を「維持／変更／回避／リスク」にまとめてください。

避けるべきよくある失敗

• 直近性バイアス。直近のコミットが最も信頼できると決めつけないでください。現在の状態には、以前の多くの判断が積み重なっていることがよくあります。履歴をたどってください。