Deep Investigation

調査の精度が落ちる原因は、調査手法の巧拙ではない。ほぼ常に次に集約される。

1. 確認した事実と推測が混ざる — 読み手が検証できなくなる
2. 出典が実在しない / 又聞きである — 検証可能に見えて検証できない
3. 最初に浮かんだ仮説で走り出す — 反証を探さないので、当たっていても偶然になる
4. 不明点を憶測で埋める — 聞けば5秒で済むことに、外れた前提で何十分もかける
5. やったことを全部書く — 読み手が結論を探す作業を肩代わりさせられる

このスキルは、これらを構造で防ぐ。気をつけるのではなく、手順として不可能にする。

Phase 0: 調査の設計

問いを立て直す

依頼をそのまま調査しない。検証可能な問いに変換してから始める。

変換した問いを最初に一行で宣言する。ズレていればユーザーがここで止められる。

調査の重さを合わせる

過剰調査はコストの無駄であって、精度ではない。

• 軽 (S): 答えが1〜2ファイルで確定する。Phase 0は問いの確認1行のみ。Phase 2の仮説列挙を省略した場合はPhase 3も省略する（検証すべき仮説がないため）。Phase 1の事実収集と出典付けだけは省略しない — 出典のない [確認] が出る事故は規模と無関係。報告は「問い/結論/根拠」だけ
• 中 (M): 複数モジュールにまたがる／選択肢が複数ある。標準フロー
• 重 (L): アーキテクチャ判断、原因不明の不具合、技術選定。全Phase実施

迷ったらMで始め、規模が判明した時点で宣言して切り替える。

調査タイプを判定し、対応する参照ファイルを読む

• コードベース内の調査 → references/codebase.md
• 外部情報・技術選定 → references/tech-research.md
• 両方にまたがる場合は両方（例:「今のfetch実装をTanStack Queryに置き換えられるか」）

参照ファイル側に質問すべき事項（技術選定の判断軸など）が指定されている場合があるので、質問をまとめる前にここを済ませる。外部の情報取得が必要になる場合は、取得してよいかも同じ質問にまとめる。

不明点は憶測で埋めず、質問する

前提が曖昧なまま進めた調査は、どれだけ丁寧でも前提ごと外れる。ただし質問を、調べる手間の代わりにしない。次の順で判定する。

1. 自分で確認できるか → できるなら調べる。聞かない （コードを読めば分かること、git log で分かること、型定義を見れば分かること）
2. 確認できない場合、それが不明なままでも調査を進められるか
   • 進められない（前提が確定しないと結果ごとやり直しになる）→ 質問して回答を待つ
   • 進められる → [未確認] として記録し、続行

質問すべき典型は、調査範囲の境界、判断基準の重み、「正しい挙動」の定義、社内固有の用語が指すもの。いずれも調査からは導けない。

質問はPhase 0でまとめて出し、そこで停止する。 1つずつ聞くと往復が増える。途中で聞くのは、前提が崩れて調査方針ごと変わる時だけ。

質問の書き方は、答えやすさが精度に直結するので形を固定する。

• 自由回答を求めず、選択肢を出す
• 各選択肢で調査結果がどう変わるかを一行添える
• 暫定の既定値を示す

ユーザーへの応答経路がない実行文脈（CI・無人実行、質問を返せないサブエージェント実行など）でのみ、質問を発する代わりに既定値で進め、報告の冒頭に「確認が必要だった前提」として列挙する。この退避は、質問を届けられる場では使わない。

共通ルール（Phase 1 以降のすべてに適用）

出典のルール

手を動かした結果が最上位

ドキュメントと実挙動は食い違う。手元で実行・再現できることは、文献で済ませずに実行する。自分で実行した結果は最も強い一次情報であり、公式ドキュメントの記述より優先する。

一次ソースでなければ [確認] にしない

二次ソースしか根拠がない主張は [確認] に昇格できない。[推定] 止まりとし、根拠に (二次) と明示してURLを残す。

一次か二次かは媒体で決まらない。その主張に対して一次かで決まる。

• 個人ブログでも、自分で測ったベンチマーク値は、その数値については一次
• 公式ドキュメントでも、バージョンが違えば自分の環境については二次以下
• メンテナの「次で直す予定」は、予定があることには一次。今どう動くかの根拠にはならない

判断に迷ったら references/tech-research.md の分類表を見る。

URLは取得したものしか書かない

報告に書くURLは、そのセッション中に実際に取得し、本文で該当記述を確認したものに限る。 これを前提とするので、「取得済み」といった注記は不要。

やってはいけないこと:

• 既知URLのパスを編集して組み立てる（/v4/ → /v5/ など）
• GitHub の Issue / PR 番号を、それらしく作る
• 検索結果のタイトルやスニペットだけで、本文を読まずに引用する
• 記憶からドメインとパスを再構成する

ユーザーが貼ったURLも、取得していなければ引用しない。

取得手段がない環境では、URLを書かない。 記憶由来の情報は [推定] とし、根拠に「モデルの記憶(未検証)」と書く。存在しそうなURLを補わない。

ラベル

確信度（結論・所見の各項目に必須）

ラベルを付けられない文は、報告に書かない。

ただし推奨・判断軸・評価はこのラベルの対象外。事実ではなく判断なので、確信度ではなく、根拠のどの行に基づくかで示す。

「おそらく」「〜と思われます」「〜のはずです」を単独で使わない。使いたくなったら [推定] を付け、根拠と確認方法を書く。曖昧語は根拠の欠落を隠す働きをする。

重要度（結論・リスク・影響範囲の節でのみ使う）

根拠の各行には付けない。重要度は「どれを結論に上げるか」の判断なので、根拠側では並び順で表現する。

[!] は感覚で付けず、次のいずれかに該当する場合に限る。

• データの破壊・消失・不整合につながる
• 設計や技術選定の前提が覆る（後から直すと広範囲に波及する）
• 静かに壊れる（気づかずに本番に出る）

読み手の緊急度は書き手が決めない。影響の大きさだけを判定する。

[-] を付けたくなったら、まず削除を検討する。残す価値があるものだけ本文に置く。

Phase 1: 事実収集（結論を書かない）

このフェーズでは原因・結論・推奨を一切書かない。仮説が浮かんでも書き留めるだけにする。これが結論への飛びつきに対する最大の防御になる。

収集した事実には、その場で出典を付ける。後から付けようとすると必ず記憶で埋める。

「無い」と言う前は最低3通りの言い換えで検索する。1つの検索語で見つからなかったことを「存在しない」と結論しない。命名は揺れる。

「見つからなかった」も事実として記録する。ただし [未確認] とし、何をどう探して見つからなかったかまで書く。これがないと誰も再現できない。

Phase 2: 仮説を複数立てる

最低2つ、可能なら3つ列挙する。1つしか浮かばない場合は「なぜ他の可能性がないと言えるか」を書く。書けないなら、まだ事実が足りていない。

各仮説に次をセットで書く。

• これが正しいなら観測されるはずの事実
• これが誤りなら観測されるはずの事実

後者が書けない仮説は反証不能なので、仮説として扱わない。捨てるか、書けるまで具体化する。

Phase 3: 検証（反証を先にやる）

まず本命を1つ決める。Phase 1 で集めた事実と矛盾しない仮説のうち、外れたときの手戻りが大きいものから検証する。事実だけで順位が付かない場合は、検証コストが低い順にする。「もっともらしさ」で選ばない。

本命の仮説を裏付ける証拠より先に、それを否定する証拠を探す。順番が重要で、裏付けを先に見つけると探索がそこで止まる。

• 反証が見つかった → 仮説を捨てる。捨てた記録は報告に残す
• 反証が見つからず、予測した事実が観測できた → [確認] に昇格
• 検証コストが高く実施しなかった → [未確認] のまま残し、確認方法を書く

本命が反証で落ちたら、残った仮説から同じ基準で次の本命を選び直し、反証探しから繰り返す。落ちた順に飛びつかない。

すべての仮説が反証されたら、結論を作らずPhase 1に戻る。 全滅は「事実が足りていない」というシグナルであって、無理に絞り込む場面ではない。戻れない場合（コスト・権限・手段がない）は結論を [未確認] とし、反証済みの仮説と、次に何を確認すれば絞り込めるかを書く。

本命が [確認] に昇格しても、残りの仮説を「たぶん違う」で流さない。各仮説を「否定（反証と出典）」か「未検証（実施しなかった理由）」のどちらかに確定させ、## 退けた可能性 に書く。どちらにも割り当てられないものは、まだ検証が終わっていない。

検証していない仮説を消去法で結論にしない。 「他が違ったからこれだろう」は [推定] であって [確認] ではない。

Phase 4: 報告

書かないもの

• 読んだファイルの列挙（判断に効いた箇所だけを file:line で示す）
• 調査手順の実況（「まず〜を確認しました。次に〜」）
• 一般論の前置き（「〜は重要な観点です」）
• 結論を繰り返すまとめ段落

報告の長さは、調査の労力ではなく読み手が判断に必要な情報量に比例させる。

テンプレート

## 問い
（Phase 0 で立て直した問い。1行）
規模: S / M / L

## 結論
（3行以内。問いへの直接の答え。各項目にラベルを付ける）
- [確認] 〜
- [推定] 〜

## 根拠
（重要度順に並べる。調査順・時系列に並べない）
- [確認] 〜 — `src/foo/bar.ts:42`
- [確認] 〜 — 実行: `pnpm why foo` → 出力2行目
- [確認] 〜 — https://... (2026-08-04 / v5.2)
- [推定] 〜 — 根拠(二次): https://... (2026-08-04)
            / 確認方法: `node_modules/foo/index.d.ts:88` を読む

## 影響範囲
（影響範囲調査のときのみ。壊れ方の段階で分ける → `references/codebase.md`）
- [!][確認] 〜 — `src/foo/bar.ts:42`

## 退けた可能性
- [確認] 仮説B: 否定 — `src/baz.ts:10` で〜のため
- [未確認] 仮説C: 未検証 — 検証には〜が必要（実施しなかった理由）

## リスク・未確認
（種別はラベルで分ける。確定したリスクと、調べていない事項は別物）
- [!][確認] 〜 — `src/foo/bar.ts:42`
- [未確認] 〜 —（未確定の理由。調べたなら試した内容と、確定に必要なもの）

## 次のアクション
（あれば。なければ節ごと削除）

S規模では「問い/結論/根拠」だけでよい。節を無理に埋めない。

調査ログが必要な場合は <details> で畳むか別ファイルに分ける。本文には出さない。

提出前チェック

機械的に判定できるものだけを挙げる。すべてにチェックが付く状態にしてから提出する。

• 結論・所見のすべての文にラベルが付いている（推奨・判断軸は対象外）
• [確認] の全行に出典（file:line / 実行コマンド / URL）がある
• URL出典に取得日と対象バージョンが付いている
• [未確認] の全行に、未確定の理由か、確定に必要なものが書かれている
• (二次) は [推定] の行にのみ付いている（[確認] には付き得ない）
• URLはすべてそのセッションで取得したものである
• [!] は結論・リスク・影響範囲の節にのみ付いている（根拠の節には付けない）
• 「退けた可能性」節がある（S規模を除く）。退けた仮説が0件なら、なぜ他の可能性がないと言えるかを書く
• 「読んだファイル一覧」「調査手順の説明」が入っていない
• 曖昧語（おそらく・思われます・はずです）をラベルなしで使っていない

最後に一度、結論だけを読み返す。それだけでユーザーが次の判断を下せなければ、結論の書き方が悪い。