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

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

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 - 任意のタイムアウトを条件ポーリングに置き換えます

関連スキル：

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

実環境での効果

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

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