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. 失敗するテストケースを作成する

   • 可能な限りシンプルに再現する
   • 可能であれば自動テストにする
   • テストフレームワークがない場合は、単発のテストスクリプトを作成する
   • 修正前に必ず用意する
   • 適切な失敗テストを書くには、agent-team:tdd スキルを使用する

2. 修正を 1 つ実装する

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

3. 修正を検証する

   • テストは通るようになりましたか？
   • ほかのテストに影響はありませんか？
   • 問題は実際に解決しましたか？

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

   • 停止する
   • 修正を何回試しましたか？
   • 3 回未満の場合：フェーズ 1 に戻り、新しい情報をもとに再分析する
   • 3 回以上の場合：停止して、アーキテクチャを見直す（下記のステップ 5）
   • アーキテクチャについて話し合う前に、修正 #4 を試みない

5. 修正が 3 回以上失敗した場合：アーキテクチャを見直す

   アーキテクチャに問題があることを示すパターン：

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

   停止して、根本的な前提を問い直します。

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

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

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

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

次のような考えが浮かんだら注意してください。

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

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

修正が 3 回以上失敗した場合： アーキテクチャを見直してください（フェーズ 4.5 を参照）。

間違った進め方をしているときの人間のパートナーからのサイン

次のような軌道修正を見逃さないでください。

• 「それは起きていないのでは？」— 確認せずに思い込んでいます
• 「それで……を確認できますか？」— 証拠を集めるべきでした
• 「推測はやめて」— 理解しないまま修正を提案しています
• 「徹底的に考えて」— 症状だけでなく、根本的な前提を問い直す必要があります
• 「行き詰まっているの？」（苛立った様子）— 進め方がうまくいっていません

こうしたサインがあったら： 停止してフェーズ 1 に戻ります。

よくある自己正当化

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

クイックリファレンス

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

プロセスをたどっても「根本原因が見つからない」場合

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

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

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

補助的な手法

これらの手法は体系的なデバッグの一部であり、このディレクトリで利用できます。

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

関連スキル：

• agent-team:tdd - 失敗するテストケースの作成、修正の検証、検証が完了する前に完了を宣言しないために使用します

実際の効果

デバッグセッションでの実績：

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