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"
   

   これにより、失敗している層がわかります：（secrets → workflow ✓、workflow → build ✗）

5. データフローを追跡する

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

   逆向きに追跡する手法については、root-cause-tracing スキルを参照してください

   簡易版：

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

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

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

1. 正常に動作する例を探す

   • 同じコードベース内で、類似する正常なコードを見つける
   • 壊れているコードと似ていて、正常に動作するものは何ですか？

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

   • パターンを実装する場合は、リファレンス実装を最後まで読む
   • ざっと読み流さず、すべての行に目を通す
   • 適用する前に、パターンを完全に理解する

3. 違いを特定する

   • 正常に動作するものと壊れているものでは、何が違いますか？
   • どんなに小さくても、違いをすべて列挙する
   • 「関係ないはず」と決めつけない

4. 依存関係を理解する

   • これに必要な他のコンポーネントは何ですか？
   • 必要な設定、構成、環境は何ですか？
   • どのような前提がありますか？

フェーズ 3：仮説と検証

科学的手法：

1. 仮説を 1 つ立てる

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

2. 最小限の変更で検証する

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

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

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

4. わからないとき

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

フェーズ 4：実装

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

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

   • 可能な限りシンプルな再現
   • 可能であれば自動テスト
   • フレームワークがない場合は単発のテストスクリプト
   • 修正前に必ず作成すること

2. 単一の修正を実装

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

3. 修正を検証

   • テストは通るようになったか？
   • ほかのテストに問題は起きていないか？
   • 問題は実際に解決したか？

4. 修正が機能しない場合

   • そこで止める
   • 試した修正の数を数える
   • 3 回未満の場合：フェーズ 1 に戻り、新しい情報をもとに再分析する
   • 3 回以上の場合：そこで止めて、アーキテクチャを見直す（下記のステップ 5）
   • アーキテクチャについて話し合わずに、修正 4 を試さない

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

   アーキテクチャ上の問題を示すパターン：

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

   そこで止めて、根本的な前提を見直します：

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

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

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

危険信号 — そこで止めて、手順に従う

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

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

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

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

よくある正当化

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

クイックリファレンス

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

手順を踏んでも「根本原因がない」と判明した場合

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

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

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

他のスキルとの連携

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

• root-cause-tracing - コールスタックをたどって原因を特定する方法
• defense-in-depth-validation - 根本原因の特定後に検証を追加する

実際の効果

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

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