debug

体系的なデバッグ

概要

場当たり的な修正は時間を浪費し、新たなバグを生みます。応急処置的なパッチは根本的な問題を覆い隠してしまいます。

中核原則: 修正を試みる前に、必ず根本原因を特定してください。症状への対処は失敗です。

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

鉄則

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.md を参照してください。

   簡易版:

   • 不正な値はどこから発生しているのか？
   • 不正な値を渡したのは何か？
   • 発生源が見つかるまで追跡を続けてください
   • 症状ではなく発生源で修正してください

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

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

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

   • 同じコードベース内で、類似した動作するコードを探してください
   • 壊れている部分に似ていて、動作しているものは何ですか？

2. 参照実装と比較する

   • パターンを実装する場合は、参照実装を最後まで完全に読んでください
   • 流し読みせず、すべての行を読んでください
   • パターンを完全に理解してから適用してください

3. 相違点を特定する

   • 動作しているものと壊れているものの違いは何ですか？
   • どんなに小さくても、すべての相違点を書き出してください
   • 「それは影響しないはずだ」と決めつけないでください

4. 依存関係を理解する

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

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

科学的方法:

1. 単一の仮説を立てる

   • 「Y という理由で X が根本原因だと考える」と明確に述べてください
   • 書き出してください
   • 曖昧にせず、具体的にしてください

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

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

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

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

4. わからないときは

   • 「X がわからない」と述べてください
   • 知っているふりをしないでください
   • 助けを求めてください
   • さらに調査してください

フェーズ 4：実装

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

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

   • 可能な限りシンプルに再現します
   • 可能であれば自動テストを作成します
   • フレームワークがない場合は、その場限りのテストスクリプトを作成します
   • 修正前に必ず作成します
   • 適切な失敗テストを書くには、tdd スキルを使用します

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％は、調査が不十分です。

補助的な手法

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

• root-cause-tracing.md - コールスタックをさかのぼってバグを追跡し、最初の引き金を見つけます
• defense-in-depth.md - 根本原因を特定した後、複数のレイヤーに検証を追加します
• condition-based-waiting.md - 任意に設定したタイムアウトを、条件をポーリングする方式に置き換えます

関連スキル：

• tdd - 失敗するテストケースを作成する場合（フェーズ4、ステップ1）
• verify - 成功を宣言する前に、修正が機能したことを検証します

実際の効果

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

• 体系的なアプローチ：修正まで15～30分
• 場当たり的な修正：2～3時間の試行錯誤
• 初回での修正率：95％対40％
• 新たに発生するバグ：ほぼゼロ対頻発