| name | systematic-debugging |
| description | バグを場当たり修正せず、根本原因を特定してから直すためのデバッグ手順。再現→切り分け→根本原因→検証の順で進める。バグ・デバッグ・原因不明・落ちる・再現しない・CIが赤・flakyなテスト・想定外の挙動に遭遇したときに使用する。「デバッグして」「なぜ落ちる」「原因を調べて」などのときにも使用する。 |
Systematic Debugging
症状を隠すのではなく、根本原因を特定してから直す。
推測で修正を重ねると、別の場所を壊したり、同じバグが形を変えて再発する。原因を説明できるまで、修正コードを書かない。
鉄則
- 根本原因を特定するまで修正しない。「たぶんここ」で直さない
- 1度に1つの仮説だけ検証する。複数箇所を同時にいじらない
- 3回直しても直らなければ、設計を疑う。個別のパッチではなく構造の問題
4フェーズ
1. 再現
- エラーメッセージ・スタックトレースを最後まで読む。要約で判断しない
- 確実に再現する最小手順を見つける。再現しないバグは直せない
- flakyなら、再現率・タイミング・環境差(並行実行、時刻、乱数、キャッシュ)を記録する
2. 切り分け
- 直近の変更を疑う:
git log・直近のdiff・git bisect で「動いていた地点」との差分を取る
- 問題の範囲を二分探索で狭める。入力・レイヤー・依存を1つずつ外して切り分ける
- 「どこまでは正しいか」を確定させ、故障点を1箇所に追い込む
3. 根本原因
- 1つの具体的な仮説を立てる(「Xの条件でYがnullになる」)。曖昧な「なんか変」で止めない
- ログ・デバッガ・最小の再現コードで仮説を検証する。当てずっぽうに print を撒かない
- 症状(NPE、500、白画面)ではなく、それを引き起こした原因まで遡る
4. 検証
- まずバグを捉える失敗するテストを書く(testing の Red)
- そのテストを通す最小の修正を入れる。ついでのリファクタや無関係な変更を混ぜない
- テストがGreenになり、再現手順で症状が消えたことを実際に確認する
- 同じ原因が他の箇所にもないか横展開して確認する
適用の判断
使うべきとき
- 原因が自明でないバグ、再現条件が不明なバグ
- 一度直したのに再発する、直したら別が壊れる
- flakyなテスト、CIだけで落ちる
不要なとき
- 原因が一目で分かるタイポや明白な誤り
- エラーメッセージが直接原因を示している軽微な修正
関連