systematic-debugging

体系的なデバッグ

基本原則

推測せず、体系的に調査してください。

修正を3回試しても失敗したら、いったん止まり、アーキテクチャを見直してください。

フェーズ1：問題を理解する

情報を集める

1. 期待される動作は何ですか？
2. 実際の動作はどうなっていますか？
3. いつから失敗し始めましたか？
4. 最近、何が変わりましたか？

一貫して再現する

• 最小限の再現ケースを作成する
• 再現するための手順を正確に記録する
• 決定論的に発生するのか、断続的に発生するのかを特定する

まずは簡単な点を確認する

• 接続されていますか？（サービスの実行状況、依存関係のインストール状況）
• 正しい環境にいますか？
• ファイルを保存しましたか？
• キャッシュをクリアしましたか？

フェーズ2：根本原因をたどる

逆方向にたどる手法

1. 問題のある値はどこに現れますか？
2. どこからこの値が渡されましたか？
3. 原因が見つかるまで上流へたどり続けます
4. 症状ではなく、原因を修正してください

正常に動作する例を探す

• 同じコードベース内で、似た正常動作するコードを見つける
• 壊れているものと似ていて、正常に動作するものは何ですか？
• 参照例と比較する

違いを特定する

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

フェーズ3：仮説を立てる

科学的手法

1. 仮説を1つだけ立てる
2. 仮説が正しければ、何が確認できるかを予測する
3. 検証するためのテストを設計する
4. テストを実行する
5. 仮説が誤っていたら、新しいデータに基づいて新たな仮説を立てる

複数の仮説を同時に立てない

• 一度に扱う仮説は1つだけにする
• 次に進む前に、仮説を完全に検証する
• デバッグのアプローチを混在させない

フェーズ4：修正を実装する

まず失敗するテストを書く

• バグを再現するテスト
• 修正前にはテストが失敗すること
• 修正後にはテストが成功すること

一度に1つだけ修正する

• 変更は1つだけ
• 「ついでに」改善しない
• リファクタリングをまとめて行わない

完全に検証する

• 元のテストが成功する
• ほかのテストが壊れていない
• 問題が実際に解決している
• エッジケースが網羅されている

フェーズ5：修正がうまくいかない場合

失敗するたびに

1. いったん止まる
2. 数える：修正を何回試しましたか？
3. < 3 の場合：フェーズ1に戻り、新しい情報をもとに再分析する
4. ≥ 3 の場合：いったん止まり、アーキテクチャを見直す

修正を3回以上試して失敗した場合

アーキテクチャ上の問題を示すパターン：

• 修正のたびに、ほかの場所で新しい問題が見つかる
• 修正に「大規模なリファクタリング」が必要になる
• 修正のたびに新たな症状が発生する

いったん止まり、次の点を確認してください：

• このパターンは根本的に妥当ですか？
• これは適切な抽象化ですか？
• 設計し直すべきですか？

デバッグツール

ログ戦略

// Add context to logs
console.log('[ComponentName] methodName:', {
  input,
  state: relevantState,
  timestamp: Date.now()
});

二分探索デバッグ

1. 問題が疑われるコードの中間地点にログを追加する
2. バグがその前にあるか後にあるかを判断する
3. 特定できるまで繰り返す

ラバーダックデバッグ

問題を声に出して説明する：

• 何が起きるべきですか？
• 実際には何が起きていますか？
• 何を試しましたか？
• どんな前提を置いていますか？

よくある落とし穴

こうした間違いを避ける

• 一度に複数のことを変更する
• 原因が分かっていると思い込む
• 根本原因ではなく症状を修正する
• 修正が実際に機能することを検証しない
• 回帰テストを追加しない

危険信号

• 「自分のマシンでは動く」
• 「昨日は動いていた」
• 「何も変更していない」
• 「それが問題のはずはない」