interrogation-debugging

取り調べ：体系的なデバッグ

概要

場当たり的な修正は時間を浪費し、新たなバグを生みます。付け焼き刃のパッチでは、真犯人を逃がしてしまいます。

基本原則： 修正を試みる前に、必ず根本原因を見つけてください。症状への対処は無効です。

この手順の文面に違反することは、デバッグの精神に違反することです。

鉄の掟

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

「ブリーフ」を完了していないなら、修正を提案することはできません。これはオメルタです。

使用する場面

あらゆる技術的な問題で使用してください：

• テストの失敗
• 本番環境のバグ
• 予期しない動作
• パフォーマンスの問題
• ビルドの失敗
• 統合の問題

特に次のような場合に使用してください：

• 時間に追われている（緊急時は推測に頼りたくなります）
• 「ちょっとした修正ですぐ直せそう」と思える
• すでに複数の修正を試した
• 以前の修正がうまくいかなかった
• 問題を完全には理解していない

次のような場合も省略しないでください：

• 問題が単純そうに見える（単純なバグにも根本原因があります）
• 急いでいる（焦ると、必ず手戻りが発生します）
• ドンが「今すぐ直せ」と言っている（手当たり次第に試すより、体系的に進めるほうが速いです）

4つのフェーズ

次のフェーズに進む前に、各フェーズを必ず完了してください。

ブリーフ

どんな修正も試みる前に：

1. 証拠を読む

   • エラーや警告を読み飛ばさない
   • 多くの場合、そこに正確な解決策が書かれています
   • スタックトレースを最後まで読む
   • 行番号、ファイルパス、エラーコードを記録する

2. 事件を再現する

   • 安定して発生させられますか？
   • 正確な手順は何ですか？
   • 毎回発生しますか？
   • 再現できない場合 → 推測せず、さらにデータを集める

3. 最近の変更を確認する

   • 何が変わって、この問題が起きた可能性がありますか？
   • Git の差分、最近のコミット
   • 新しい依存関係、設定の変更
   • 環境の違い

4. すべての境界で証拠を集める

   システムに複数のコンポーネントがある場合（CI → ビルド → 署名、API → サービス → データベース）：

   修正を提案する前に、診断用の計測処理を追加する：

   各コンポーネントの境界で：

   • コンポーネントに入るデータを記録する
   • コンポーネントから出るデータを記録する
   • 環境や設定が正しく引き継がれているか確認する
   • 各レイヤーの状態を確認する

   問題がどこで発生するかを示す証拠を集めるため、一度実行します。 その後、証拠を分析して、問題のあるコンポーネントを特定します。 さらに、その特定したコンポーネントを調査します。

5. データの流れを追跡する

   エラーがコールスタックの深い位置で発生している場合：

   • 不正な値はどこから来ていますか？
   • どの呼び出し元が、不正な値を渡してこれを呼び出しましたか？
   • 発生源を見つけるまで、逆方向に追跡する
   • 症状ではなく、発生源を修正する

反対尋問

修正する前にパターンを見つける：

1. 正常に動作する例を見つける

   • 同じコードベース内で、似た正常動作するコードを探す
   • 壊れているものと似ていて、正常に動作するものは何ですか？

2. 参照実装と比較する

   • パターンを実装する場合は、参照実装を最後まで完全に読む
   • ざっと読み流さない ― すべての行を読む
   • 適用する前に、そのパターンを完全に理解する

3. 違いを特定する

   • 正常に動作するものと壊れているものの違いは何ですか？
   • どんなに小さな違いでも、すべて列挙する
   • 「それは関係ないはず」と決めつけない

4. 依存関係を理解する

   • これには他にどのコンポーネントが必要ですか？
   • どのような設定、構成、環境が必要ですか？
   • どのような前提を置いていますか？

仮説

科学的手法：

1. 仮説を1つ立てる

   • 「Y であるため、X が根本原因だと考えます」と明確に述べる
   • 書き留める
   • 曖昧にせず、具体的にする

2. 最小限のテストを行う

   • 仮説を検証するために、可能な限り最小の変更を行う
   • 一度に変更するのは1つの変数だけにする
   • 複数のことを一度に修正しない

3. 続行する前に検証する

   • うまくいきましたか？ はい → 命中です
   • うまくいきませんでしたか？ 新しい仮説を立てる
   • 修正を重ねて追加しない

4. わからない場合

   • 「X を理解できていません」と言う
   • わかったふりをしない
   • 助けを求めるか、さらに調査する

修正

症状ではなく、根本原因を修正してください。

1. 失敗するテストケースを作成する

   • 可能な限りシンプルに再現する
   • 可能であれば自動テストを作成する
   • テストフレームワークがない場合は、使い捨てのテストスクリプトを作成する
   • 修正する前に必ず作成する
   • 適切な失敗テストを書くには gangsta:drill-tdd を使用する

2. 修正を1つだけ実装する

   • 特定した根本原因に対処する
   • 変更は一度に1つだけ
   • 「ついでに」改善しない
   • リファクタリングをまとめて行わない

3. 修正を検証する

   • テストは通るようになったか？
   • ほかのテストに影響はないか？
   • 問題は実際に解決したか？
   • 成功を宣言する前に gangsta:sweep-verification を使って検証する

4. 修正がうまくいかない場合

   • 停止する
   • 修正を何回試したか数える
   • 3回未満の場合：新たに得た情報をもとに再分析するため、「概要」に戻る
   • 3回以上の場合：停止してエスカレーションする（下記のステップ5）
   • アーキテクチャについて話し合うことなく、修正を4回目まで試みてはいけない

5. 修正に3回以上失敗した場合：「ドン」にエスカレーションする

   アーキテクチャの劣化を示すパターン：

   • 修正のたびに、別の箇所で新たな共有状態／結合／問題が明らかになる
   • 修正の実装に「大規模なリファクタリング」が必要になる
   • 修正のたびに、ほかの箇所で新たな症状が発生する

   停止して、根本的な前提を問い直す：

   • このパターンは根本的に妥当か？
   • ただ惰性でこのパターンを続けていないか？
   • 症状への対処を続けるのではなく、アーキテクチャをリファクタリングすべきではないか？

   これ以上修正を試みる前に、ドンと話し合ってください。

   これは仮説の失敗ではなく、アーキテクチャの誤りです。

危険信号 — 停止して手順に従う

次のように考えていることに気づいたら：

考え	実際
「とりあえず応急処置して、後で調査しよう」	今すぐ調査してください。応急処置は積み重なります。
「Xを変えてみて、どうなるか見よう」	それはデバッグではなく、当てずっぽうです。「概要」に戻ってください。
「複数の変更を加えて、テストを実行しよう」	何が効いたのか切り分けられません。一度に1つだけ変更してください。
「テストは省略して、手動で確認しよう」	手動での確認は証拠になりません。
「たぶんXだろう。直してみよう」	「たぶん」ということは、まだ調査できていません。
「完全には理解していないけれど、うまくいくかもしれない」	うまくいくかも、は当てずっぽうです。「概要」に戻ってください。
「もう一度修正を試そう」（2回以上失敗した後）	3回失敗したらアーキテクチャの問題です。エスカレーションしてください。
「主な問題はこれです：[一覧]」	調査せずに列挙するのは不適切です。
データフローを追跡する前に解決策を提案する	停止してください。まず追跡し、その後で提案してください。

これらはすべて、停止して「概要」に戻るべきサインです。

ドンからの、やり方が間違っているというサイン

次のような方向転換を促す言葉に注意してください：

• 「それは起きていないのですか？」— 検証せずに決めつけています
• 「それで……がわかるのですか？」— 証拠を集める手段を追加すべきでした
• 「当てずっぽうはやめてください」— 理解せずに修正を提案しています
• 「もっとよく考えてください」— 症状だけでなく、根本的な前提を問い直してください
• 「行き詰まっているのですか？」（苛立った様子で）— そのアプローチはうまくいっていません

こうした言葉を見聞きしたら： 停止して、「概要」に戻ってください。

よくある自己正当化

言い訳	実際
「問題は単純だから、手順は必要ない」	単純な問題にも根本原因はあります。単純なバグなら、手順に従ってもすぐに済みます。
「緊急だから、手順を踏む時間はない」	系統的なデバッグは、当てずっぽうを繰り返すより速いです。
「まずこれを試して、その後で調査しよう」	最初の修正が、その後の進め方の基準になります。最初から正しく行ってください。
「修正がうまくいったと確認してからテストを書こう」	テストしていない修正は定着しません。先にテストを書けば、修正が効いたことを確認できます。
「一度に複数の修正をすれば時間を節約できる」	何が効いたのか切り分けられません。新たなバグの原因になります。
「参考資料が長すぎるので、パターンを応用しよう」	部分的な理解では、必ずバグが発生します。最後まで読んでください。
「問題がわかった。直してみよう」	症状が見えていることと、根本原因を理解していることは別です。
「もう一度修正を試そう」（2回以上失敗した後）	3回以上失敗したらアーキテクチャの問題です。ドンにエスカレーションしてください。

クイックリファレンス

フェーズ	主な作業	成功基準
概要	エラーを読み、再現し、変更を確認し、証拠を集めます	WHAT と WHY を理解する
反対尋問	動作する例を見つけ、比較します	違いを特定する
仮説	仮説を立て、最小限のテストを行います	仮説を確認するか、新しい仮説を立てる
決着	テストを作成し、修正し、検証します	バグが解決し、テストが通る

調査しても根本原因が見つからない場合

体系的な調査の結果、問題が本当に環境依存、タイミング依存、または外部要因によるものだと分かった場合：

1. プロセスは完了しています
2. 調査した内容を記録します
3. 適切な対処（再試行、タイムアウト、エラーメッセージ）を実装します
4. 今後の調査に備えて、監視やログ記録を追加します

ただし：「根本原因なし」とされるケースの95%は、調査が不十分です。

関連スキル

• gangsta:drill-tdd — 失敗するテストケースを作成する場合（決着、ステップ1）
• gangsta:sweep-verification — 成功を宣言する前に、修正が機能したことを検証します

オメルタ遵守

• 真実の掟：すべての調査結果は、具体的なコード、エラー出力、または証拠を示します
• 仕様は絶対：修正は推測ではなく、診断した根本原因に基づいています