systematic-debugging

系統的なデバッグ

概要

場当たり的な修正は時間を浪費し、新たなバグを生みます。手早いパッチは根本的な問題を覆い隠します。

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

このプロセスの文言だけでなく、その精神に反することも、デバッグの精神に反することです。

鉄則

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

フェーズ 1 を完了していない場合、修正を提案してはいけません。

使用するタイミング

あらゆる技術的な問題に使用してください。テストの失敗、バグ、予期しない動作、パフォーマンスの問題、ビルドの失敗、統合の問題が対象です。

特に使用する状況： 時間に追われているとき、「手早く修正できそう」と思えるとき、すでに複数の修正を試したとき、問題を十分に理解できていないとき。

次のような場合も省略しないでください： 問題が単純に見えるとき、急いでいるとき、マネージャーから「今すぐ」修正するよう求められているとき。

クイックリファレンス — 4 つのフェーズ

フェーズ	主な活動	成功基準
1. 根本原因	エラーを読む、再現する、変更点を確認する、証拠を集める	何が起きているか、そしてなぜ起きているかを理解する
2. パターン	動作する例を見つけ、比較する	相違点を特定する
3. 仮説	仮説を立て、最小限のテストを行う	仮説を確認するか、新たな仮説を立てる
4. 実装	テストを作成し、修正して、検証する	バグが解決し、テストに合格する

各フェーズの詳細な手順については、references/four-phases-detailed.md を参照してください。

危険信号 — 作業を止めてプロセスに従う

次のような考えが浮かんだら：

• 「とりあえず手早く修正して、調査は後で」
• 「X を変えて、うまくいくか試してみよう」
• 「複数の変更を加えて、テストを実行しよう」
• 「テストは省略して、手動で確認しよう」
• 「たぶん X だ。修正してみよう」
• 「よくわからないけれど、これでうまくいくかもしれない」
• 「主な問題はこちらです：[調査せずに修正案を列挙する]」
• データフローを追跡する前に解決策を提案する
• 「もう一度だけ修正を試そう」（すでに 2 回以上試している場合）
• 修正のたびに別の場所で新たな問題が見つかる

これらはすべて、作業を止めてフェーズ 1 に戻るべきという合図です。

修正に 3 回以上失敗した場合： アーキテクチャを見直してください（詳細リファレンスのフェーズ 4 を参照）。

補助テクニック

• root-cause-tracing.md — コールスタックを遡ってバグを追跡する
• defense-in-depth.md — 複数のレイヤーに検証を追加する
• condition-based-waiting.md — 任意のタイムアウトを条件ポーリングに置き換える

関連スキル：

• test-driven-development — 失敗するテストケースの作成に使用します（フェーズ 4）
• verification-before-completion — 成功を宣言する前に修正が機能したことを検証します

ユーザーの兆候、合理化の一覧、「根本原因が見つからない」場合の指針については、references/debugging-signals.md を参照してください。