systematic-debugging

体系的なデバッグ

概要

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

中核原則: 修正を試みる前に、必ず根本原因を特定してください。症状への対処は失敗です。

このプロセスの文言に違反することは、デバッグの精神に違反することです。

鉄則

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

フェーズ 1 を完了していなければ、修正を提案することはできません。

使用するタイミング

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

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

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

• 時間的な圧力がかかっているとき(緊急時は推測に走りたくなります)
• 「ちょっとした修正を一つ」が明らかに正解に思えるとき
• すでに複数の修正を試したとき
• 前回の修正がうまくいかなかったとき
• 問題を完全には理解していないとき

次の場合でも省略しないでください:

• 問題が単純に見えるとき(単純なバグにも根本原因はあります)
• 急いでいるとき(急ぐと必ず手戻りが発生します)
• マネージャーが「今すぐ直せ」と求めるとき(体系的に進める方が、やみくもに試すより速いです)

4 つのフェーズ

次のフェーズに進む前に、各フェーズを必ず完了しなければなりません。

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

いかなる修正を試みる前にも:

1. エラーメッセージを注意深く読む

   • エラーや警告を読み飛ばさないでください
   • 正解そのものが書かれていることが多いです
   • スタックトレースを最後まで読んでください
   • 行番号、ファイルパス、エラーコードをメモしてください

2. 一貫して再現させる

   • 確実に再現できますか？
   • 正確な手順は何ですか？
   • 毎回発生しますか？
   • 再現しない場合は、推測せずにさらにデータを収集してください

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

   • この問題を引き起こしうる変更は何ですか？
   • Git の差分、最近のコミット
   • 新しい依存関係、設定の変更
   • 環境の違い

4. 複数コンポーネントから成るシステムで証拠を収集する

   システムが複数のコンポーネントを持つ場合(CI → ビルド → 署名、API → サービス → データベース):

   修正を提案する前に、診断用の計測を追加してください:

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   例(多層システム):

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   これによって判明すること: どの層で失敗しているか(シークレット → ワークフロー ✓、ワークフロー → ビルド ✗)

5. データフローを追跡する

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

   後方追跡の完全な手法については、このディレクトリにある root-cause-tracing.md を参照してください。

   簡易版:

   • 不正な値はどこから発生しているのか？
   • 不正な値を渡したのは何か？
   • 発生源が見つかるまで追跡を続けてください
   • 症状ではなく発生源で修正してください

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

修正する前にパターンを見つけてください:

1. 動作する例を見つける

   • 同じコードベース内で、類似した動作するコードを探してください
   • 壊れている部分に似ていて、動作しているものは何ですか？

2. 参照実装と比較する

   • パターンを実装する場合は、参照実装を最後まで完全に読んでください
   • 流し読みせず、すべての行を読んでください
   • パターンを完全に理解してから適用してください

3. 相違点を特定する

   • 動作しているものと壊れているものの違いは何ですか？
   • どんなに小さくても、すべての相違点を書き出してください
   • 「それは影響しないはずだ」と決めつけないでください

4. 依存関係を理解する

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

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

科学的方法:

1. 単一の仮説を立てる

   • 「Y という理由で X が根本原因だと考える」と明確に述べてください
   • 書き出してください
   • 曖昧にせず、具体的にしてください

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

   • 仮説を検証するために、可能な限り最小の変更を加えてください
   • 一度に変更する変数は 1 つだけにしてください
   • 複数のことを同時に修正しないでください

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

   • うまくいきましたか？ はい → フェーズ 4 へ
   • うまくいきませんでしたか？ 新しい仮説を立ててください
   • 既存の修正の上に、さらに修正を重ねないでください

4. わからないときは

   • 「X がわからない」と述べてください
   • 知っているふりをしないでください
   • 助けを求めてください
   • さらに調査してください

フェーズ 4：実装

症状ではなく、根本原因を修正します。

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

   • 可能な限りシンプルに再現します
   • 可能であれば自動テストを作成します
   • テストフレームワークがなければ、一度限りのテストスクリプトを作成します
   • 修正前に必ず作成します
   • 適切な失敗テストを作成するには、tdd スキルを使用します

2. 修正を 1 つ実装する

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

3. 修正を検証する

   • テストは成功しましたか？
   • ほかのテストは壊れていませんか？
   • 問題は実際に解決しましたか？

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

   • 停止します
   • これまでに試した修正の数を数えます
   • 3 回未満の場合：フェーズ 1 に戻り、新しい情報をもとに再分析します
   • 3 回以上の場合：停止して、アーキテクチャに疑問を持ちます（下記のステップ 5）
   • アーキテクチャについて話し合わずに、修正 4 を試してはいけません

5. 3 回以上の修正に失敗した場合：アーキテクチャに疑問を持つ

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

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

   停止して、基本原則を問い直します：

   • このパターンは根本的に妥当ですか？
   • 「ただ惰性で続けている」だけではありませんか？
   • 症状の修正を続けるのではなく、アーキテクチャをリファクタリングすべきではありませんか？

   これ以上修正を試みる前に、人間のパートナーと話し合ってください。

   これは仮説の失敗ではありません。アーキテクチャが間違っています。

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

次のように考えている自分に気づいたら：

• 「とりあえず応急処置して、あとで調べよう」
• 「X を変えて、うまくいくか試してみよう」
• 「複数の変更を加えて、テストを実行しよう」
• 「テストは省略して、手動で確認しよう」
• 「たぶん X だろう。修正してみよう」
• 「完全には理解していないけれど、これでうまくいくかもしれない」
• 「パターンでは X となっているけれど、別のやり方に変えてみよう」
• 「主な問題は次のとおりです：[調査せずに修正を列挙する]」
• データフローを追跡する前に解決策を提案する
• 「もう 1 回修正を試そう」（すでに 2 回以上試している場合）
• 修正のたびに、別の場所で新たな問題が明らかになる

これらはすべて、停止してフェーズ 1 に戻るべきサインです。

3 回以上の修正に失敗した場合： アーキテクチャに疑問を持ちます（フェーズ 4.5 を参照）。

作業が間違っていることを示す人間のパートナーのサイン

次のような軌道修正に注意してください：

• 「それは実際に起きているの？」— 確認せずに決めつけています
• 「それで……がわかるの？」— 証拠を集める手順を追加すべきでした
• 「推測はやめて」— 理解する前に修正を提案しています
• 「徹底的に考えて」— 症状だけでなく、基本原則を問い直す必要があります
• 「行き詰まっているの？」（苛立った様子）— アプローチがうまくいっていません

このようなサインを見たら： 停止してフェーズ 1 に戻ります。

よくある正当化

言い訳	実態
「問題は単純だから、手順はいらない」	単純な問題にも根本原因があります。単純なバグなら、手順に従ってもすぐに解決できます。
「緊急なので、手順に従う時間がない」	体系的なデバッグのほうが、当てずっぽうで試行錯誤するより速く済みます。
「まずこれを試してから、調べよう」	最初の修正が、その後の進め方を決めます。最初から正しく進めてください。
「修正がうまくいったと確認してから、テストを書こう」	テストしていない修正は定着しません。先にテストを書けば、修正を検証できます。
「複数の修正を一度に行えば時間を節約できる」	何が効いたのか切り分けられず、新たなバグの原因になります。
「参考資料が長すぎるので、パターンを応用しよう」	中途半端な理解は、必ずバグにつながります。最後まで読んでください。
「問題はわかった。修正しよう」	症状を見つけることと、根本原因を理解することは別です。
「もう 1 回修正を試そう」（2 回以上失敗した後）	3 回以上失敗したなら、アーキテクチャに問題があります。パターンに疑問を持ち、再び修正するのはやめてください。

クイックリファレンス

フェーズ	主な作業	成功基準
1. 根本原因	エラーを読み、再現し、変更を確認し、証拠を集めます	何が、なぜ起きているかを理解している
2. パターン	動作する例を探して比較します	違いを特定している
3. 仮説	理論を立て、最小限のテストを行います	仮説が確認されたか、新たな仮説が立っている
4. 実装	テストを作成し、修正し、検証します	バグが解決し、テストが成功している

調査の結果「根本原因が見つからない」場合

体系的な調査の結果、問題が実際に環境依存、タイミング依存、または外部要因によるものだと判明した場合：

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

ただし：「根本原因が見つからない」ケースの95%は、調査が不十分です。

関連するテクニック

以下のテクニックは体系的なデバッグの一部であり、このディレクトリで利用できます：

• root-cause-tracing.md - コールスタックをさかのぼってバグを追跡し、最初の引き金を見つけます
• defense-in-depth.md - 根本原因を見つけた後、複数の層に検証を追加します
• condition-based-waiting.md - 任意に設定したタイムアウトを、条件をポーリングする方式に置き換えます

関連するスキル：

• tdd - 失敗するテストケースの作成に使用します（フェーズ4、ステップ1）
• superpowers:verification-before-completion - 成功を宣言する前に、修正が機能したことを検証します

実際の効果

デバッグセッションから：

• 体系的なアプローチ：修正まで15～30分
• 手当たり次第に修正するアプローチ：2～3時間の試行錯誤
• 初回修正成功率：95% 対 40%
• 新たに発生するバグ：ほぼゼロ 対 頻繁に発生