Systematic Debugging

体系的なデバッグ

概要

行き当たりばったりの修正は時間を無駄にし、新たなバグを生みます。手早いパッチは根本的な問題を覆い隠します。

基本原則： 修正を試みる前に、必ず根本原因を見つけてください。症状だけを修正するのは失敗です。

このプロセスの文言だけを守って精神を守らないのは、デバッグの精神に反する行為です。

鉄の掟

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

使用する場面

あらゆる技術的な問題に使用します。

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

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

• 時間に追われている場合（緊急時は推測に頼りたくなります）
• 「手早く 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. データフローを追跡する

   呼び出しスタックの深い位置でエラーが発生している場合：

   逆向きにたどる手法については、skills/root-cause-tracing を参照してください。

   簡易版：

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

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

修正する前にパターンを見つけます。

1. 正常に動作する例を見つける

   • 同じコードベース内で、似た正常動作のコードを探す
   • 問題のあるコードと似ていて、正常に動作するのはどのコードですか？

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

   • パターンを実装する場合は、リファレンス実装を最後まで読む
   • 斜め読みせず、すべての行を読む
   • 適用する前に、パターンを十分に理解する

3. 違いを特定する

   • 正常に動作するものと問題のあるものには、どのような違いがありますか？
   • どんなに小さくても、すべての違いを書き出す
   • 「これは関係ない」と決めつけない

4. 依存関係を理解する

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

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

科学的な方法で進めます。

1. 仮説を 1 つ立てる

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

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

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

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

   • 機能しましたか？ はい → フェーズ 4 へ
   • 機能しませんでしたか？ 新しい仮説を立てる
   • 修正をさらに重ねない

4. 分からない場合

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

フェーズ 4：実装

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

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

   • 可能な限り簡単に再現できるようにします
   • 可能であれば自動テストにします
   • テストフレームワークがない場合は、単発のテストスクリプトを作成します
   • 修正前に必ず作成します
   • 適切な失敗テストの書き方については、skills/testing/test-driven-development を参照してください

2. 単一の修正を実装する

   • 特定した根本原因に対処します
   • 一度に変更するのは 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%は、調査が不十分です。

他のスキルとの連携

このスキルは、次のスキルと連携します：

• skills/root-cause-tracing - コールスタックをさかのぼる方法
• skills/defense-in-depth - 根本原因の特定後に検証を追加する方法
• skills/testing/condition-based-waiting - フェーズ2で特定したタイムアウトを置き換える方法
• skills/verification-before-completion - 成功を報告する前に修正が機能したことを検証する方法

実際の効果

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

• 体系的なアプローチ：修正まで15～30分
• 場当たり的な修正：2～3時間を費やしても進展なし
• 初回での修正成功率：95%対40%
• 新たに発生するバグ：ほぼゼロ対頻発