why

Why

コードの背後にある動機や意図を調査します。なぜこのように実装されたのでしょうか？どのようなエッジケースが考慮されたのでしょうか？どのようなプロダクト、ビジネス、運用上の制約が設計を形作ったのでしょうか？どのような代替案が却下され、その理由は何でしょうか？

how スキルと対をなすものです。how はコードが何を行い、どのように動作するかを説明します。why は、その形に至った要因を明らかにします。

このスキルの仕組み

過去の経緯は、ソース管理履歴、課題やチケットの追跡、長文ドキュメント、リアルタイムのチームチャット、インフラストラクチャのオブザーバビリティ、エラーや例外の追跡、プロダクト分析用データウェアハウスという7つの証拠カテゴリにまたがっています。質問だけから答えがどこにあるかを予測することはできません。そのため、このスキルは実行時に利用可能な MCP を列挙し、それぞれをカテゴリに対応付け、7つすべてを並列で検索してから、確信度を明示的に調整しつつ情報を統合します。検索したカテゴリで結果が得られなかったことも、意思決定の経緯を示す重要な証拠です。肯定的な発見と併せて報告してください。既定の方針は、最小限にとどめることではなく、網羅することです。

作業姿勢

慎重で、用心深く、正確な調査者として取り組んでください。断片的な記録から過去の事例を組み立てる探偵のように考えてください。記録が乏しい場合は、そのことを伝えてください。

具体的には、次のとおりです。

• 物語より証拠を優先します。 まず材料を集め、それがどのような説明を裏付けるかを見極めます。物語を先に決め、それに合う証拠を集めてはいけません。
• 洗練さより正確さを優先します。 滑らかな言い換えより、正確な引用と出典を優先します。読者がどの主張も出典までたどり、1分以内に検証できるようにしてください。
• 目にしていないものを考慮します。 見つかった証拠は全体ではなく、一部です。結論を出す前に、別の説明が正しいとしたらどのような証拠があるはずか、また、それを探したかどうかを考えてください。
• 欠落を明示します。 スレッドが途切れている、情報源を検索できない、質問に答えがない場合は、その欠落を記録してください。権威ありげな推測で取り繕ってはいけません。
• 意図して留保を示します。 証拠が間接的な場合は、「～のようです」「～である可能性があります」「～を示唆しています」といった表現で伝えてください。確信度に応じた表現は出力の重要な要素であり、情報を統合する側が変更してよい文体上の選択肢ではありません。
• コードを読むだけの近道に頼りません。 コードから分かるのは、何をするかであり、なぜ存在するかが分かることはほとんどありません。コードの形から意図を推測するのは避けてください。

この姿勢は、単なる免責事項ではなく、実際の作業方法です。

中核となる認識論

このスキルは、断片的な過去の証拠からパッチワーク状の理解を組み立てます。チケットは古くなります。チャットのスレッドは削除されます。コミットメッセージは事実と異なることがあります。PR の説明と実装の間に、関係者の考えが変わることもあります。元の作者がすでに会社を離れている場合もあります。

何を把握していて、何を推測しているのかを、徹底して正直に示してください。目標は満足できる物語を作ることではなく、証拠を明らかにし、確信度を適切に調整して、ユーザーが判断できるようにすることです。

原則：

• すべてに出典を付けます。 意図に関するすべての主張は、具体的なコミットハッシュ、PR 番号、チケット ID、ドキュメント URL、チャットのパーマリンク、またはコードコメントを参照してください。出典を示せない場合、それは事実ではなく推論であり、そのように明示する必要があります。
• 「～だから」より「～のようです」を優先します。 証拠が間接的な場合は留保を示してください。断定的な表現は、直接的で明示的な証拠がある場合に限ります。
• 矛盾を表に出します。 2つの情報源が食い違っている場合は、両方を示してください。自分の説明に合う方を、黙って選んではいけません。
• 欠落を認めます。 検索したどの情報源にも質問への答えがない場合は、そのことを伝えてください。自信ありげな推測よりも、「理由は分かりませんでした」と正直に伝える方が適切です。
• 複数の仮説が成り立つことを認めます。 証拠が複数の説明に当てはまる場合は、それぞれを裏付ける証拠とともに提示してください。判断材料を組み立てるのはユーザーに任せます。
• 後付けの正当化に注意します。 現在は筋が通っているコードでも、当時はすでに当てはまらない理由で書かれたのかもしれませんし、正当な理由がなかった可能性もあります。後付けで意図を作り上げてはいけません。

確信度の枠組みと表現のガイドラインについて詳しくは、references/epistemics.md を参照してください。情報を統合する側は、これに従う必要があります。

ステップ 1. 対象と質問を理解する

ユーザーが何を尋ねているのかを解析します。対象は通常、コードの一部、パターン、機能、または名前の付いた設計上の判断です。質問は通常、次のいずれかです。

• 「なぜ X はこのように設計されたのですか？」設計の根拠。
• 「なぜ Y ではなく X を行うのですか？」トレードオフや代替案。
• 「どのようなエッジケースがきっかけになったのですか？」防御的な考慮。
• 「どのようなビジネス上または製品上の制約が原因だったのですか？」外部からの要因。
• 「なぜこのコードはまだ存在するのですか？」デッドコードの領域。
• 「X の歴史はどうなっていますか？」広範な調査。

対象が曖昧な場合（明確な参照先のない「なぜこのようにしているのですか？」など）は、会話のコンテキスト（開いているファイル、最近の編集、カーソル位置、直前に話題にした内容）から最善の推測をします。解釈が違っていた場合にユーザーが訂正できるよう、解釈を簡潔に示してから調査を進めます。

ステップ 2. コード上の根拠を特定する

調査担当者を立ち上げる前に、具体的なコードに調査の根拠を置きます。次の情報が必要です。

• 関連するファイルパスと行範囲
• 主要なシンボル（関数名、クラス名、定数）
• 最初のコミット一覧。対象に最後に触れた数件のコミット。
• マージコミットの PR 番号（件名のパターン (#1234)）

これらをこの場でまとめます。手間はかからず、どの調査担当者にも必要な情報です。

# Blame target lines for last-touch commits
git blame -L <start>,<end> <file>

# Full file history, with patches, through renames
git log --follow -p -- <file>

# Last N commits touching the file, PR numbers visible
git log --oneline -20 -- <file>

# Extract PR numbers from a commit message
git log -1 --format=%B <commit>

内容のあるコミットについては、gh で PR の説明とディスカッションを取得します。

gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews

これを初期コンテキストとして記録します（ファイルパス、シンボル、コミット、PR 番号、関連するチケット ID）。調査担当者に渡し、同じ情報を再調査しないようにします。

ステップ 3. 並行して調査担当者を立ち上げる（デフォルトの進め方）

デフォルトでは、並行調査を全面的に行います。 各証拠カテゴリはそれぞれ異なる種類のシステムに存在し、どのカテゴリに答えがあるかは、質問だけでは調べるまで判断できません。そのため、デフォルトで利用可能なすべてのカテゴリを並行して調べます。

検出

調査担当者を起動する前に、Cursor 環境で利用可能な MCP を一覧表示してください。利用可能なツールのマップがある場合は、それを使用してください。ない場合は、Cursor が公開している mcps/ ディレクトリを調べ、有効な MCP サーバーを確認してください。

利用可能な各 MCP を、次の証拠カテゴリのいずれかに分類してください。

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

ソース管理には git と gh を通じて常にアクセスできます。残りの 6 カテゴリは、MCP 名、サーバーの指示、ツール名、リソースの説明を使って分類してください。複数のカテゴリに当てはまりそうな MCP は、主な証拠に合うカテゴリを選んでください。曖昧なケースはカバレッジマップに記録してください。

最小限ではなく、完全なカバレッジマップを目指してください。課題管理システムから結果が得られなかった場合も、その判断がチケット化されていないという証拠であり、それ自体に意味があります。検索を省略せず、結果がなかったことを記録してください。

該当する調査担当者はすべて、単一のメッセージで起動し、並行して実行してください。カテゴリごとに調査担当者を 1 人割り当てることで、それぞれが 1 つのツールのクエリ用語と結果形式に特化できます。1 人のエージェントに複数の MCP を担当させないでください。

サブエージェントの設定（各担当者）：

• subagent_type: generalPurpose
• model: 設定済みの why-investigators モデル（既定値は composer-2.5-fast）
• readonly: false（エージェントモード）。readonly／Ask モードは使用しないでください。 MCP へのアクセスが取り除かれ、MCP を使う調査担当者が完全に機能しなくなります。ソース管理の調査担当者は readonly でも安全ですが、モードは統一してください。調査担当者は、引き続き何も書き込まないでください。これは姿勢の問題であり、サンドボックスではありません。

各調査担当者には、次のものを渡してください。

1. references/investigator-prompt.md にある基本プロンプト
2. 選択した MCP に対応するカテゴリ別プレイブック references/sources/<source>.md。references/source-playbook.md の例を参考に調整してください
3. 対象コードが防御的な実装に見える場合は、分野横断的な references/sources/incident-postmortem.md（null チェック、リトライロジック、タイムアウト処理、レート制限、フィーチャーフラグ、送信先制御、OOM ハンドラーなど）
4. ステップ 2 のコードアンカー（ファイルパス、シンボル、コミットハッシュ、PR 番号、チケット ID）
5. ユーザーの元の質問

調査担当者の構成。利用可能な証拠カテゴリごとに 1 人

対応する MCP があるカテゴリごとに、調査担当者を 1 人起動してください。各担当者は、ツールまたは MCP を 1 つだけ担当します。

各項目には、そのカテゴリに実際に含まれる情報と、そこから特有に明らかになる「なぜ」が記載されています。結果として何が返ってくると想定されるか、カテゴリから何も得られなかった場合にどのような不足として報告するか、そして（まれに、明らかに無関係と証明できる場合に限り）調査を省略する理由を判断するために使用してください。カテゴリ間で情報が重複することはありますが、それぞれ他のカテゴリでは取得できない種類の証拠を担います。

1. ソース管理の調査担当者。Git の履歴、PR 用の gh、コードコメント、テストを調べます。常に起動してください。唯一、必ず利用できる情報源です。レビュー時に記録された実装上の判断理由を明らかにするのに最適です。問題を説明する PR の記述、代替案を議論するレビューコメント、明白でない制約を示すインラインコメント、動機となったエッジケースを示すテスト名、チケットやインシデントに関連付けるコミットメッセージなどを調べます。実際にマージされた差分に直接結び付いているため、最も信頼性の高い情報源です。

2. 課題／チケット管理システムの調査担当者（Linear、Jira、GitHub Issues、Plane、Shortcut MCP など）。チケット、プロジェクト文書、ステータス更新、仕様添付ファイルを調べます。プロダクトまたはビジネス上の推進要因を明らかにするのに最適です。顧客からの要望（「Acme が SOC2 監査のために X を必要としている」など）、コンプライアンスの期限、親イニシアチブの背景（「第 3 四半期のエンタープライズ対応」など）、チケット単位でのスコープ変更、動機を分類するラベル（customer:*、incident-followup、compliance、perf-regression）などを調べます。「なぜ」がエンジニアリングの外部にある場合に、最も有力な情報源です。

3. 長文ドキュメント調査ツール（例：Notion、Confluence、Google Docs、Coda MCP）。PRD、仕様書、RFC、設計ドキュメント、ADR、事後検証、チームページ、議事録などを対象とします。長文に記された設計根拠の発見を得意とします。問題提起、「検討した代替案」や「却下したアプローチ」の明示的なセクション、優先順位を定める戦略文書、最終決定を記録したADR、コードに直接結び付く事後検証のアクション項目などを見つけます。コードになる前に、なぜそうするのかが書き残されている場所を調査します。

4. リアルタイムチームチャット調査ツール（例：Slack、Discord、Microsoft Teams、Mattermost MCP）。機能名やシンボルの検索、PR URLへの言及、インシデントチャンネル（#sev-*、#incident-*）、リリース日前後の投稿者ハンドルの活動などを対象とします。ドキュメントに残されなかったリアルタイムの議論の発見を得意とします。インシデント中の緊急対応における決定、PR作成者とレビュアー間の質疑応答、「Y なので X に決めた」という気軽なスレッド、PRDを作成するほどではない小さな変更の根拠などを見つけます。ソース管理、チケット、ドキュメントの記録が乏しい場合に特に重要です。

5. インフラストラクチャ可観測性調査ツール（例：Datadog、New Relic、Honeycomb、Grafana、Splunk MCP）。メトリクス、モニター、ダッシュボード、ログ、APM トレース、正式なインシデントなどを対象とします。インフラストラクチャと実行時の視点で調査します。コードの動機となったインフラストラクチャと実行時の実態の発見を得意とします。コード内の定数と一致するモニターのしきい値、PR のマージ直前の期間に発生したメトリクスの急増、事後検証のアクション項目として作成されたダッシュボード、対象コードに言及したインシデントの時系列などを見つけます。対象コードがインフラストラクチャのシグナル（タイムアウト、再試行、レート制限、サーキットブレーカー）に反応する場合に特に有効です。

6. エラー／例外トラッキング調査ツール（例：Sentry、Rollbar、Bugsnag、Airbrake MCP）。問題、イベント、スタックトレース、リリースなどを対象とします。防御的または修正のためのコードの動機となった具体的な例外とエラーの推移の発見を得意とします。対象の関数を通るスタックトレース、初回検出から最終検出までの期間が PR のリリース日を挟む問題、特定のバージョンでエラーが止まったことを示すリリースとの相関などを見つけます。catch ブロック、null ガード、型チェック、再試行など、さまざまな防御処理の調査に特に有効です。

7. プロダクト分析データウェアハウス調査ツール（例：Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP）。プロダクト分析イベント、実験やフィーチャーフラグの公開テーブル、使用状況や課金イベント、クエリー履歴、データウェアハウスのテレメトリなどを対象とします。プロダクトとデータの視点で調査します。インフラストラクチャのメトリクスではなく、リリース日前後のユーザーの行動とデータの実態を把握することで、インフラストラクチャ可観測性を補完します。コードに影響を与えたプロダクトとデータの実態の発見を得意とします。機能の使用状況の推移（ゼロから段階的に増加する急激な変化は、この PR で機能がリリースされた強い証拠です）、リリース判断に結び付く実験／フラグの公開データ、しきい値定数の由来を明らかにするリリース前の分布（例：limit = 128 * 1024 がアップロードサイズ列の p99 と一致する）、移行／バックフィルにおけるデータパイプラインの規模を示す証拠などを見つけます。フラグで制御されるコード、実験に基づくリリース、データ移行、「この数値の出所は何か」という疑問の調査に特に有効です。

調査担当者を省略する場合

省略できるのは、最終的な「Sources Consulted」セクションに記載する明示的な書面による正当な理由がある場合に限ります。有効な理由は次の2つです。

• この環境では、そのカテゴリに該当する MCP が利用できない。 これは選択ではなく、ギャップとして明記してください。例：「リアルタイムのチームチャットは調査対象から除外しました。一致する MCP が利用できず、会話記録を検索できませんでした。」
• その情報源が関連しないことを証明できる。 単に「おそらく関連しない」では不十分です。高い基準が求められます。例：「エラー／例外の追跡は調査対象から除外しました。対象は実行時のコードパスを持たないビルド時スクリプトです。」 「おそらくエラー追跡には記録されていません。エラーではなく機能だからです。」では不十分です。

「これは純粋な機能コードなので、エラー追跡には何もないでしょう」も十分な理由ではありません。「長文ドキュメントに記載されているとは思えません」も同様です。検索を実行し、結果がないことをそのまま示してください。調査担当者が空の結果を返すコストは、サブエージェント1つ分です。実在する設計ドキュメントを見落とすコストは、誤った回答です。

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

ステップ4. 統合する

統合担当のサブエージェントを1つ起動します。

• subagent_type: generalPurpose
• model: 設定済みの why-synthesizer モデル（デフォルトは claude-opus-4-8-thinking-xhigh）
• readonly: false（エージェントモード）。統合担当は引用を抜き取り確認する品質チェックを行うため、MCP にアクセスする必要が生じる場合があります。Readonly／Ask モードでは MCP が除外されるため、目的を果たせません。

統合担当に渡すもの：

1. 調査担当者の調査結果。結果がなかった場合や、正当な理由を添えて省略したカテゴリも含めます
2. ステップ2のコードアンカー（ファイルパス、シンボル、コミットハッシュ、PR 番号、チケット ID）
3. ユーザーの元の質問
4. references/epistemics.md の認識論的フレームワーク
5. references/synthesizer-prompt.md の統合担当プロンプトテンプレート

役割は最終出力の作成です。確信度を明示し、根拠を引用した説明をまとめ、「判明していること」と「推測していること」のセクションを明確に分け、ギャップや結果がなかった情報源についても正直に認めます。

ステップ5. 提示する

統合担当の出力をユーザーに提示します。明確さのための軽微な編集や、会話の文脈からの補足は可能ですが、確信度を示す表現は書き換えないでください。認識論的な枠組みこそが、この成果物の本質です。より断定的に聞こえるように留保を取り除くことは、このスキルが防ごうとしているまさにその失敗です。

出力形式

最終出力は次の構成にします。必要に応じて調整できますが、確信度の区分は維持してください。

質問。ユーザーの質問を簡潔に言い換えます。

該当するコード。ファイルパス、行の範囲、主要なシンボルを記載します。読者が対象を把握できるよう、1〜2行でまとめます。

判明したこと（直接的な証拠）。明示的な出典（PR #、チケット ID、ドキュメント URL、チャットのパーマリンク、コミットハッシュ、ファイル名と行番号を含むコードコメント）を添えて主張を記載します。各箇条書きには、文書による証拠がある事項を記載します。現在形を使い、出典を引用するか言い換えます。

合理的に推測できること。間接的な証拠、または複数のシグナルの組み合わせによって十分に裏付けられているものの、明示されてはいない主張を記載します。各箇条書きでは推論の過程を説明します。「A と B を踏まえると、C である可能性があります」のように、断定を避けた表現を使います。

対立する仮説。証拠が複数の解釈と整合する場合は、仮説を列挙します。それぞれについて、仮説、その仮説を裏付ける証拠、反証となる証拠を示します。記録から結論を出せない場合、無理に結論を出しません。（明確な答えがある場合は、このセクションを省略します。）

わかっていないこと。明示的に残っている不足点を記載します。ユーザーの質問のうち、証拠から回答できなかった点も含めます。検索して何も見つからなかった出典を具体的に示します。「この具体的な閾値について議論しているチケットは見つかりませんでした」のように、検索した内容を具体的に記載すると、「なぜかわかりません」よりも役立ちます。

調査した出典。何も見つからなかった調査担当者も含め、調査担当者ごとに1行で記載します。読者が、（a）どの MCP に問い合わせたか、（b）どれが空振りだったか、（c）どれを、なぜスキップしたかを一目で把握できるようにします。この網羅状況の一覧によって、読者は調査範囲を評価し、見落としがあれば指摘できます。

各行は次の形式にします：- <出典>：<検索した内容>。<見つかった内容、または「該当する結果なし」、または「スキップ。理由」>。

例：

• ソース管理（git/gh）：git log --follow backend/retry.ts、PR #49074、#47812 を調査。PR #49074 で指数バックオフが導入され、ENG-4421 にリンクされていることを確認。
• 課題トラッカー（Linear）：「retry」と ENG-4421 を検索。親課題 ENG-4421 は見つかったが、バックオフのパラメーターについての議論はなし。
• 長文ドキュメント（Notion）：「retry policy」、「backend retries」、「ENG-4421」を検索。該当する結果なし。
• リアルタイムのチームチャット（Slack）：スキップ。この環境では該当する MCP を利用できません。未調査のため、会話記録の確認ができていません。
• インフラストラクチャの可観測性（Datadog）：retry_count メトリクスと、2024-08-14 前後のモニターを検索。PR #49074 と同日に「Upstream 5xx rate > 1%」というモニターが作成されたことを確認。
• エラー／例外トラッキング（Sentry）：retry.ts を通るスタックトレースがある、2024 年 8 月に初めて検出された問題を検索。PR 前の週に急増した問題 SENTRY-3821 を確認。
• プロダクト分析ウェアハウス（Databricks）：<your_analytics_db>.<schema>.stg_backend_upstream_retry に対し、2024-08-14 前後の30日間を対象にクエリを実行。障害として分類されたイベントの1日あたりの件数が、PR 前の約1.2k件から、PR 後は50件未満に減少。関連する移行クエリがないか、system.query.history も確認。見つかったものはなし。

「Sources Consulted」ブロックの後に、ユーザーの「なぜ」という質問が実際にコードを変更する前段階にあたる場合は、変更計画に使えるよう、系譜に関する調査結果を「維持する／変更する／避ける／リスク」の制約セットに変換します。

避けるべきよくある失敗

• 自信たっぷりのストーリー仕立て。乏しい証拠から、もっともらしい筋書きを組み立ててしまうことです。引用のない箇条書きは「判明したこと」ではなく、「推測」または「仮説」に記載します。
• コード自体の意図を裏付ける証拠として、コードを引用する。「null をチェックしているので、null の場合を処理する」は仕組みの説明であり、動機ではありません。動機は外部の情報源（PR での議論、チケット、コメント、会話）から得るか、推論として明記します。
• 直近の情報への偏り。最新のコミットが決定的な根拠だと思い込むことです。現在の形は、過去の多くの判断が積み重なった結果であることがよくあります。さかのぼって調査します。
• 迎合的な同意。ユーザーが理由を示唆した場合（「パフォーマンスのためだと思うのですが？」など）は、それを仮説として扱い、ただ同意するのではなく、証拠を独立して確認します。
• 不明点のセクションを省略する。分からなかったことを正直に記すことも、価値の一部です。
• 先入観から調査担当を省略する。「長文ドキュメントにはたぶん含まれない」や「これはエラー追跡の話ではない」と最初から決めつけ、検索しないことです。デフォルトで7つすべてを調査する姿勢が、これを防ぎます。見つからなかったという結果もデータポイントです。検索を省略するのは盲点です。
• 調査担当を1つのエージェントにまとめる。各 MCP にはそれぞれ固有の検索語彙、結果の形式、注意点があります。まとめると専門性が薄まり、調査範囲の把握も難しくなります。必ずカテゴリごとに1人の調査担当を割り当てます。

参照ファイル

• references/epistemics.md。確信度の段階と表現のガイドです。統合担当はこれに従う必要があります。
• references/investigator-prompt.md。調査担当のサブエージェント向け基本プロンプトテンプレートです。
• references/source-playbook.md。以下のカテゴリ別プレイブックへのインデックスです。
• references/sources/*.md。各カテゴリにつき自己完結した例示プレイブックが1つと、分野横断的な incident-postmortem.md があります。調査担当には、担当カテゴリに一致するファイルを1つ渡し、利用可能な MCP に合わせて調整します。
• references/synthesizer-prompt.md。出力形式を含む、統合担当のサブエージェント向けプロンプトテンプレートです。