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"
   

   これにより、失敗している層がわかります：（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. 失敗するテストケースを作成する

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

   # Create test with bun (preferred)
   bun test my-fix.test.ts
   
   # Or with npm
   npm test -- my-fix.test.ts
   

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

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

3. 修正を検証する

   • テストは通るか？
   • ほかのテストに影響していないか？
   • 問題は実際に解決したか？

   # Run full test suite
   bun test  # or: npm test
   
   # Run specific test
   bun test --grep "my fix"
   

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

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

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

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

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

   STOP して基本方針を見直す：

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

   さらに修正を試す前に、人間のパートナーと話し合ってください

   これは仮説が外れたのではなく、アーキテクチャが間違っています。

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

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

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

これらはすべて STOP を意味します。フェーズ 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％
• 新たに発生するバグ：ほぼゼロ 対 よく発生