investigate

基本原則

根本原因を理解するまでは、修正しません。 検証済みの証拠を用いて、原因がどのように症状を引き起こすかを説明します。一見明白な原因であっても検証が必要です。原因がすでに特定されている場合は、新たに仮説を立て直す必要はありません。

ステップ 1 — 症状を把握する

報告内容、利用可能なログ、プロジェクトの設定、過去の試行から、以下の情報を収集します。調査に実質的な影響を与える情報が欠けている場合に限り、質問します。

• 正確な症状： エラー、誤った出力、クラッシュ、または無反応の内容をそのまま記録します。
• 再現方法： 確実な発生条件、発生頻度、断続的な障害の条件。
• 発生時期： いつから始まったか、および関連する可能性のある変更。
• 環境： 発生する場所と、正常に動作する環境との関連する違い。
• 過去の試行： 何をテストまたは変更し、その結果どうなったか。

ステップ 2 — 仮説を立てる

利用可能な証拠に基づいて、考えられる原因を提案します。証拠による裏付けの強さで順位を付け、割合をでっち上げたり、リストを一定の件数に合わせて水増ししたりせず、不確実性を説明します。それぞれの仮説について、原因を見分けるための確認方法を示します。

Hypothesis: [possible cause]
Evidence: [observations supporting it]
Would rule it out: [contradicting observation]
Next check: [how to obtain evidence that distinguishes it from alternatives]

一般的な分類：

• データに関する誤った前提：値の欠落、想定外の型や形状。
• 状態またはタイミング：並行処理、古いキャッシュ、操作の順序。
• 設定または環境の違い。
• 外部依存関係やライブラリの動作の変化。
• 関連するソースコードの変更によるリグレッション。

ある領域に原因があるはずがないというユーザーの見解は、調査の優先度には影響しますが、それだけでその領域を原因から除外することはできません。

ステップ 3 — 影響を最小限に抑えて仮説を検証する

既存のログ、デバッガー、設定の確認、制御された再現を優先します。原因を見分ける能力、コスト、運用への影響を考慮して確認方法を選びます。

観察だけでは不十分な場合は、許可された範囲内で元に戻せる診断用の変更を加えます。変更内容を記録し、既存の作業を保持したうえで、確認後に一時的な計測処理を削除するか、診断のみを目的とした依存関係の変更を元に戻します。診断用の変更を残すのは、合意済みの修正に意図的に含める場合に限ります。

仮説	確認方法の例
値が欠落している	デバッガーまたは一時的な対象限定ログで、関連する境界における値を確認する
操作が競合している	制御された再現で、操作のタイミングと状態遷移を比較する
設定が異なる	関連する設定のみを比較する。秘密情報はマスキングし、機密性の高い値には、存在の有無や一致の確認を優先する
依存関係の動作が変化した	共有環境を変更せず、隔離された再現環境で関連するバージョンを比較する

影響を受ける動作と症状の発生時期に結び付く変更がないか、ソースコードの履歴を確認します。コミット数や日数を一律に決めるのではなく、関連する証拠を追います。各確認の結果を記録し、仮説を見直すか除外します。

ステップ 4 — データフローを追跡する

証拠を用いて、影響を受ける経路を追跡しながら仮説を確認します。

[Request/Event enters at: ]
  → [Layer 1] — state here: [what you found]
  → [Layer 2] — state here: [what you found]
  → [Where behavior diverges from expected] — state here: [what you found]
  → [Where the symptom manifests]

実際の動作が期待される動作から最初に乖離する、検証済みの箇所を特定します。該当する場合は正確なファイル名と行番号を示し、それがどのように症状を引き起こすかを説明します。さらに上流へ追跡し、それ以前の原因を除外します。新たな証拠が得られた場合は、ステップ 2～4 を相互に参照しながら進めます。

ステップ 5 — 原因を確認して修正する

検証済みの根本原因に対処する、最小限の変更を行います。編集する前に、原因と、提案する変更によってなぜ解決するのかを説明します。関連する未解決の問題については、ユーザーの結果や今回の修正範囲に影響する場合に限り言及します。

テストの作成順序は、プロジェクトのルールとリスクに応じて決定します。元の失敗を引き起こす条件下で再現し、修正前のバージョンでは失敗し、修正後は成功する回帰テストを追加します。非公開の実装詳細ではなく、関連する観測可能な動作を検証します。再現が不安定な場合や必要な環境を利用できない場合は、修正を実証済みと断言せず、証拠の限界と残っている検証作業を報告します。

ユーザーまたはプロジェクトのコミット方針に従います。指定がない場合は、修正と回帰テストを別々のコミットにし、それぞれの意図した変更だけをステージングします。テストの作成順序とコミット順序は別の判断です。修正より先にテストを作成し、別々のコミットにする場合でも、修正の後にテストをコミットできます。

ステップ 6 — 検証する

修正後に元の再現手順をもう一度実行し、回帰テストが修正前後で期待どおりに動作することを検証します。影響を受ける動作に関連するチェックを実行し、プロジェクトの全テスト実行ルールに従います。一時的な診断用変更を削除したか、意図的に残したかを確認します。

症状が続く場合は、観測された結果に基づいて仮説とデータフローを見直します。修正を再度試みる前に、それを正当化する新たな証拠を特定します。それ以上試みても根拠のない推測を繰り返すことになる場合は、以下の停止条件を適用します。

ステップ 7 — 証拠を前に進められない場合は中断するか、支援を求める

次の試みで新たな証拠や異なる診断チェックが得られない場合、否定された推測を繰り返す場合、または利用できない情報、アクセス権、専門知識、承認が必要な場合は、影響を受ける修正の試みを中断します。新たな証拠を安全に得られる、独立した調査は続けます。証拠に裏付けられた次の手順であれば、それ以前に何回失敗していても進められます。

実際の阻害要因と、具体的な次の手順を報告します。

Blocked investigation: [what cannot currently be established]

Attempts and observations:
- [check or fix attempted, what changed, and observed result]

Current understanding:
[confirmed facts, remaining hypotheses, and what is uncertain]

Missing evidence or access:
[what is needed to distinguish the remaining causes]

Recommended next step:
[specific check, information request, or authorized action]