systematic-debugging

体系的なデバッグ

基本原則

根本原因を調査する前に、修正してはいけません。

根本的な問題を覆い隠す、症状だけに焦点を当てたパッチは決して適用しないでください。修正を試みる前に、なぜ問題が発生するのかを理解してください。

4 段階のフレームワーク

フェーズ 1：根本原因の調査

コードに手を加える前に：

1. エラーメッセージを注意深く読む - すべての言葉が重要です
2. 問題を一貫して再現する - 再現できなければ、修正を検証できません
3. 最近の変更を調べる - 問題が発生する前に何が変わりましたか？
4. 診断に必要な証拠を集める - ログ、スタックトレース、状態ダンプ
5. データの流れを追跡する - 呼び出しチェーンをたどり、不正な値の発生源を特定します

根本原因を追跡する手法：

1. Observe the symptom - Where does the error manifest?
2. Find immediate cause - Which code directly produces the error?
3. Ask "What called this?" - Map the call chain upward
4. Keep tracing up - Follow invalid data backward through the stack
5. Find original trigger - Where did the problem actually start?

重要な原則： エラーが表面化した箇所だけで問題を修正してはいけません。必ず元の引き金までさかのぼってください。

フェーズ 2：パターン分析

1. 動作する例を探す - 正しく動作する類似のコードを見つけます
2. 実装をすべて比較する - ざっと目を通すだけではいけません
3. 違いを特定する - 動作するものと壊れているものの違いは何ですか？
4. 依存関係を理解する - このコードは何に依存していますか？

フェーズ 3：仮説とテスト

科学的手法を適用します：

1. 明確な仮説を 1 つ立てる - 「原因 X によりエラーが発生している」
2. 最小限のテストを設計する - 一度に変更する変数は 1 つだけにします
3. 結果を予測する - 仮説が正しければ、何が起こるはずですか？
4. テストを実行する - 実行して観察します
5. 結果を検証する - 予測どおりに動作しましたか？
6. 反復するか、次に進む - 仮説が間違っていれば修正し、正しければ実装します

フェーズ 4：実装

1. 失敗するテストケースを作成する - バグの挙動を再現します
2. 修正を 1 つだけ実装する - 症状ではなく根本原因に対処します
3. テストが通ることを確認する - 修正が機能することを確認します
4. テストスイート全体を実行する - リグレッションがないことを確認します
5. 修正に失敗したら、停止する - 仮説を再評価します

重要なルール： 修正が 3 回以上連続して失敗した場合は、停止してください。これは、さらなるパッチではなく、話し合いが必要なアーキテクチャ上の問題を示しています。

警告すべき兆候 - プロセス違反

次のように考えていることに気づいたら、すぐに停止してください：

• 「とりあえず手早く修正して、調査は後で」
• 「もう一度だけ修正を試そう」（複数回失敗した後）
• 「これで動くはず」（理由を理解していないのに）
• 「ちょっと試してみよう……」（仮説なしで）
• 「自分のマシンでは動く」（違いを調査せずに）

より深刻な問題を示す兆候

連続した修正によって、異なる領域で新たな問題が明らかになることは、アーキテクチャ上の問題を示しています：

• パッチを適用するのをやめる
• 判明したことを記録する
• 先に進む前にチームで話し合う
• 設計を見直す必要があるか検討する

よくあるデバッグのシナリオ

テストの失敗

1. Read the FULL error message and stack trace
2. Identify which assertion failed and why
3. Check test setup - is the test environment correct?
4. Check test data - are mocks/fixtures correct?
5. Trace to the source of unexpected value

実行時エラー

1. Capture the full stack trace
2. Identify the line that throws
3. Check what values are undefined/null
4. Trace backward to find where bad value originated
5. Add validation at the source

「以前は動いていた」

1. Use git bisect to find the breaking commit
2. Compare the change with previous working version
3. Identify what assumption changed
4. Fix at the source of the assumption violation

断続的な失敗

1. Look for race conditions
2. Check for shared mutable state
3. Examine async operation ordering
4. Look for timing dependencies
5. Add deterministic waits or proper synchronization

デバッグのチェックリスト

バグを修正したと判断する前に：

• 根本原因を特定し、記録した
• 仮説を立てて検証した
• 症状ではなく根本原因に対処する修正である
• バグを再現する失敗テストを作成した
• 修正後、テストが通る
• テストスイート全体が通る
• 「とりあえずの修正」という正当化をしていない
• 修正が最小限で、焦点を絞っている

成功の指標

体系的なデバッグでは、場当たり的なアプローチの約 40% に対し、初回で約 95% の修正成功率を達成できます。

適切に進められている兆候：

• 修正によって新しいバグが発生しない
• バグが発生した理由を説明できる
• 類似のバグが再発しない
• 修正後のコードが単に「動くだけ」でなく、より良くなっている

他のスキルとの連携

• testing-patterns：修正する前に、バグを再現するテストを作成します