debugging

デバッグ

体系的な調査、根本原因の追跡、多層防御による検証、確認プロトコルを組み合わせた包括的なデバッグフレームワークです。

基本原則

まず根本原因を調査しない限り、修正してはいけません

場当たり的な修正は時間を浪費し、新たなバグを生みます。根本原因を見つけ、発生源で修正し、すべての層で検証してから、成功したと判断してください。

使用するタイミング

必ず使用する場面： テストの失敗、バグ、予期しない動作、パフォーマンスの問題、ビルドの失敗、統合の問題、作業完了を宣言する前

特に使用する場面： 時間に追われているとき、「応急処置」が明らかに思えるとき、複数の修正を試したとき、問題を十分に理解できていないとき、成功を宣言しようとしているとき

4 つの手法

1. 体系的なデバッグ（references/systematic-debugging.md）

適切な調査を徹底する 4 段階のフレームワークです。

• フェーズ 1：根本原因の調査（エラーを読み、再現し、変更を確認し、証拠を収集する）
• フェーズ 2：パターン分析（正常に動作する例を見つけ、比較し、相違点を特定する）
• フェーズ 3：仮説の立案とテスト（仮説を立て、最小限のテストを行い、検証する）
• フェーズ 4：実装（テストを作成し、一度で修正し、検証する）

重要なルール： 次に進む前に、各フェーズを完了してください。フェーズ 1 を完了する前に修正してはいけません。

読み込む場面： 調査と修正が必要なバグや問題があるとき

2. 根本原因の追跡（references/root-cause-tracing.md）

コールスタックをさかのぼり、バグの最初の引き金を特定します。

手法： 実行の深い箇所でエラーが発生した場合、無効なデータが発生した場所を見つけるまで、レベルごとにさかのぼって追跡します。症状ではなく、発生源を修正してください。

内容： テストへの汚染の混入箇所を二分探索する scripts/find-polluter.sh

読み込む場面： コールスタックの深い箇所でエラーが発生したとき、無効なデータがどこで発生したか不明なとき

3. 多層防御（references/defense-in-depth.md）

データが通過するすべての層で検証します。バグが起こり得ない状態にします。

4 つの層： 入力時の検証 → ビジネスロジック → 環境ガード → デバッグ用計測

読み込む場面： 根本原因の特定後、包括的な検証を追加する必要があるとき

4. 検証（references/verification.md）

検証コマンドを実行し、成功を宣言する前に出力を確認します。

絶対原則： 最新の検証証拠なしに、完了を宣言してはいけません

コマンドを実行します。出力を読みます。その後で結果を宣言します。

読み込む場面： 作業の完了、修正、またはテストの合格を宣言しようとしているとき

クイックリファレンス

Bug → systematic-debugging.md (Phase 1-4)
  Error deep in stack? → root-cause-tracing.md (trace backward)
  Found root cause? → defense-in-depth.md (add layers)
  About to claim success? → verification.md (verify first)

危険信号

次のように考えている場合は、作業を止めて手順に従ってください。

• 「とりあえず応急処置をして、調査は後で」
• 「X を変えて動くか試してみよう」
• 「おそらく X なので、修正しよう」
• 「これで動くはず」／「直ったようだ」
• 「テストに合格したので、これで終わり」

いずれも意味すること： 体系的な手順に戻ってください。