systematic-debugging

（中国語）Systematic Debugging

概要

当てずっぽうの修正は時間を無駄にし、新たなバグを生みます。応急処置では根本的な問題が隠れてしまいます。

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

このプロセスの文言に違反することは、デバッグの精神に違反することです。

鉄則

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

フェーズ 1 を完了していない場合、修正案を提示してはいけません。

使用するタイミング

あらゆる技術的な問題に使用してください。

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

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

• 時間に追われている場合（緊急時は推測に頼りたくなります）
• 「手早く修正するだけ」で済みそうに見える場合
• すでに複数の修正を試した場合
• 前回の修正が機能しなかった場合
• 問題を十分に理解できていない場合

次の場合も省略しないでください。

• 問題が単純に見える場合（単純なバグにも根本原因があります）
• 急いでいる場合（焦ると必ずやり直しが発生します）
• マネージャーが今すぐ直すよう求めている場合（場当たり的に対応するより、体系的に進める方が速く済みます）

4 つのフェーズ

次のフェーズに進む前に、各フェーズを必ず完了してください。

フェーズ 1：根本原因の調査

修正を試みる前に、必ず次のことを行ってください。

1. エラーメッセージを注意深く読む

   • エラーや警告を読み飛ばさない
   • 解決策そのものが記載されていることがよくあります
   • スタックトレースを最後まで読む
   • 行番号、ファイルパス、エラーコードを記録する

2. 一貫して再現する

   • 安定して再現できますか？
   • 正確な手順は何ですか？
   • 毎回発生しますか？
   • 再現できない場合 → 推測せず、さらにデータを集める

3. 最近の変更を確認する

   • これを引き起こす可能性のある変更は何ですか？
   • Git diff、最近のコミット
   • 新しい依存関係、設定の変更
   • 環境の違い

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. 仮説を 1 つ立てる

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

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

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

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

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

4. 分からない場合

   • 「X が理解できません」と言う
   • 分かったふりをしない
   • 助けを求める
   • さらに調べる

フェーズ 4: 実装

症状ではなく根本原因を修正する:

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

   • 可能な限り単純な再現手順にする
   • 可能であれば自動テストにする
   • テストフレームワークがない場合は、使い捨てのテストスクリプトを作成する
   • 修正の前に必ず作成すること
   • 適切な失敗テストを書くには superpowers: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. 根本原因	エラーを読む、再現する、変更を確認する、証拠を集める	WHAT と WHY を理解する
2. パターン	動作する例を探し、比較する	違いを特定する
3. 仮説	仮説を立て、最小限に検証する	仮説を確定するか、新たな仮説を立てる
4. 実装	テストを作成し、修正し、検証する	バグが解決し、テストが通る

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

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

1. プロセスを完了している
2. 調査した内容を文書化する
3. 適切な対処を実装する（リトライ、タイムアウト、エラーメッセージなど）
4. 今後の調査に備えて監視／ログを追加する

ただし: 「根本原因なし」とされるケースの95%は、調査が不完全であることが原因です。

補助的な手法

これらの手法は体系的デバッグの一部であり、このディレクトリで利用できます:

• root-cause-tracing.md - コールスタックを遡ってバグを追跡し、元のトリガーを見つける
• defense-in-depth.md - 根本原因を特定した後、複数の層で検証を追加する
• condition-based-waiting.md - 任意のタイムアウトを条件ポーリングに置き換える

関連スキル:

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

実際の影響

デバッグセッションからの結果:

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