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: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || 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. 仮説を 1 つ立てる

   • 「Y なので、X が根本原因だと考えます」と明確に述べる
   • 書き留める
   • 曖昧ではなく、具体的にする

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

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

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

   • うまくいきましたか？ はい → フェーズ 4
   • うまくいかなかった場合は、新しい仮説を立てる
   • 修正をさらに重ねない

4. わからない場合

   • 「X を理解できていません」と伝える
   • わかったふりをしない
   • 助けを求める
   • さらに調査する

フェーズ 4：実装

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

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

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

2. 修正を1つだけ実装する

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

3. 修正を検証する

   • テストは合格するようになりましたか？
   • ほかのテストは壊れていませんか？
   • 問題は実際に解決しましたか？
   • 成功を宣言する前に、superpowers:verification-before-completion スキルを使用します

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

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

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

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

   • それぞれの修正によって、別の場所に新たな共有状態、結合、問題が見つかる
   • 修正の実装に「大規模なリファクタリング」が必要になる
   • 修正するたびに、別の場所に新たな症状が発生する

   停止して、根本から見直します。

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

   さらに修正を試みる前に、人間のパートナーと話し合います。

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

危険信号 — 停止してプロセスに従う

次のように考えていることに気づいたら：

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

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

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

人間のパートナーが示す「うまくいっていない」というサイン

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

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

これらのサインに気づいたら： 停止してフェーズ 1 に戻ります。

よくある自己正当化

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

クイックリファレンス

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

プロセスによって「根本原因なし」と判明した場合

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

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

ただし： 「根本原因なし」とされるケースの 95% は、調査が不十分です。

補助的な手法

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

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