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 を使用してください

   簡易版：

   • 不正な値はどこで発生していますか？
   • 不正な値を渡しているのはどの呼び出しですか？
   • 発生源が見つかるまで上流へ追跡し続けます
   • 症状ではなく、発生源を修正します

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

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

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

   • 同じコードベース内で、似たような動作するコードを探します
   • 壊れているものと似ていて、正しく動作しているものは何ですか？

2. リファレンスと比較する

   • パターンを実装する場合、リファレンス実装を最後まで読みます
   • ざっと目を通すだけではいけません。1 行ずつ読みます
   • 適用する前に、パターンを十分に理解します

3. 違いを特定する

   • 動作するものと壊れているものには、どのような違いがありますか？
   • どんなに小さな違いでも、すべて列挙します
   • 「関係ないはず」と決めつけてはいけません

4. 依存関係を理解する

   • ほかにどのコンポーネントが必要ですか？
   • 必要な設定、構成、環境は何ですか？
   • どのような前提で動作しますか？

フェーズ 3：仮説と検証

科学的手法：

1. 仮説を 1 つ立てる

   • 「Y であるため、X が根本原因だと思います」と明確に述べます
   • 書き留めます
   • 曖昧にせず、具体的にします

2. 最小限の変更でテストする

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

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

   • うまくいきましたか？ はい → フェーズ 4
   • うまくいきませんでしたか？ 新しい仮説を立てます
   • その上からさらに修正を重ねてはいけません

4. 分からないとき

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

フェーズ 4：実装

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

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

   • 可能な限りシンプルに再現する
   • 可能であれば自動テストにする
   • テストフレームワークがない場合は、単発のテストスクリプトを作成する
   • 修正前に必ず作成する
   • まずテストが失敗することを確認する — 修正前にテストが成功しても何の証明にもなりません。失敗することを確認してから、修正して成功させます

2. 修正を 1 つ実装する

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

3. 修正を検証する

   • テストは成功するようになったか？
   • ほかのテストに不具合はないか？
   • 問題は実際に解決したか？

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

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

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

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

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

   STOP して、根本から問い直します：

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

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

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

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

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

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

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

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

人間のパートナーが示す、作業がうまくいっていないサイン

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

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

こうしたサインに気づいたら： STOP してフェーズ 1 に戻ります。

よくある合理化

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

クイックリファレンス

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

プロセスで「根本原因なし」と判明した場合

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

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

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

他のスキルとの連携

このスキルで使用が必要なもの：

• root-cause-tracing - エラーがコールスタックの深い位置にある場合に必須です（フェーズ1、ステップ5を参照）

補完的なスキル：

• defense-in-depth - 根本原因の特定後、複数のレイヤーで検証を追加します
• condition-based-waiting - フェーズ2で特定した任意のタイムアウトを置き換えます
• verification-before-completion - 成功を宣言する前に修正が機能したことを検証します

実際の効果

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

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