debug-systematic

体系的なデバッグプロトコル

推測を防ぎ、根本原因の発見を確実にする、規律ある証拠に基づいたデバッグ手法です。

4 フェーズのプロトコル

フェーズ 1：再現（事実を確認する）

目標：調査を始める前に、確実な再現手順を作成します。

実施項目：

1. バグを引き起こす正確な手順を記録する
2. 環境の詳細（OS、バージョン、設定、メモリ、ネットワーク）を記録する
3. 発生頻度を特定する：常に発生しますか？時々ですか？特定の条件下ですか？
4. 正確なエラーメッセージ、スタックトレース、スクリーンショットを取得する
5. 変数を切り分けるため、異なる環境でテストする

重要な質問：

• 最後に正常に動作したのはいつですか？
• それ以降、何が変わりましたか？（コード、依存関係、設定、インフラストラクチャ）
• 特定の環境でのみ発生しますか？
• 特定のデータでのみ発生しますか？
• タイミングに依存しますか？

成果物：問題を確実に引き起こす、明確な再現手順。

---

フェーズ 2：切り分け（範囲を絞る）

目標：調査範囲を「コードベース全体」から「特定のコンポーネント」へ絞り込みます。

手法：

二分探索：

1. 正常な状態と問題のある状態の 2 点を特定する
2. 中間点をテストする
3. 問題のある側で再帰的に調べる
4. 変更を特定するまで続ける

Git Bisect（リグレッションの場合）：

git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# Git will checkout commits for testing
# After each test:
git bisect good  # or git bisect bad
# Continue until culprit found

コードの除外：

• 問題を切り分けるため、セクションをコメントアウトする
• 最小限の再現ケースを作成する
• 必須でないものをすべて取り除く

環境の切り分け：

• 失敗する経路を分離して実行する（最小限の再現。ユーザーがテストを求めた場合に限り、ユニットテストを使用する）
• 正常な環境と問題のある環境を比較する
• 新規インストールを使用して、環境の汚染を排除する

成果物：「バグは［特定のコンポーネント／関数／行の範囲］にあります」

---

フェーズ 3：診断（根本原因を理解する）

目標：バグが「どこで」起きるかだけでなく、「なぜ」起きるのかを正確に把握します。

科学的手法：

1. 観察：実際に何が起きていますか？
2. 仮説：なぜこの現象が起きているのでしょうか？
3. 予測：仮説が正しければ、ほかに何が成り立つでしょうか？
4. 検証：証拠を使って予測を確認する
5. 反復：結果に基づいて仮説を見直す

ログ戦略：

// Add strategic logging at boundaries
console.log("[DEBUG] Function entry:", { input, state });
console.log("[DEBUG] After processing:", { result, sideEffects });
console.log("[DEBUG] Function exit:", { returnValue });

よくある根本原因：

症状	考えられる原因
ローカルでは動作するが、CI で失敗する	環境の違い、タイミング、リソース
断続的に失敗する	競合状態、不安定なネットワーク、リソース競合
動作していたのに、動作しなくなる	状態の変更、メモリリーク、キャッシュの汚染
データが間違っている	型変換、エンコーディング、タイムゾーン、精度
エラーが表面化しない	例外の握りつぶし、非同期エラー、await の欠落

成果物：証拠に基づいた、根本原因の明確な説明。

---

フェーズ 4：修正と検証（解決し、再発を防ぐ）

目標：問題を修正し、リグレッションを防ぎます。

修正プロセス：

1. 最小限の修正を実装する - 変更をできるだけ少なくする
2. 同様のパターンを確認する - ほかの場所にも同じバグがありませんか？
3. 修正の副作用を確認する - 影響する呼び出し元、入力、エラー経路を読み直す
4. 修正内容を記録する - 発生理由と予防方法を記載する

ユーザーがテストを求めた場合に限り、バグを再現する失敗テストを作成します。

検証チェックリスト：

• レビューにより、症状だけでなく、フェーズ 3 で特定した根本原因に対処していることを確認する
• 修正によってすでに得られている出力（再現結果や、作業を実行したコマンド）が、それを裏付けている
• 影響を受けるすべての環境で修正が機能する
• 新たな警告やエラーが発生していない

予防策：

• 境界にガードや検証を追加する
• 今後のデバッグを容易にするため、エラーメッセージを改善する
• ほかの開発者向けに注意点を記録する
• アーキテクチャを変更することで同様のバグを防げるか検討する

デバッグにおけるアンチパターン

してはいけないこと：

• 推測に頼り、うまくいくことを期待する（手当たり次第に変更する）
• 証拠なしに問題を把握したと思い込む
• 実際のコードの動作よりもコメントやドキュメントを信頼する
• 削除し忘れる可能性のある print 文を使って本番環境をデバッグする
• 根本原因ではなく症状を修正する
• 複数の変更を同時に行う

すること：

• 証拠をもとに前提を検証する
• 一度に一つだけ変更する
• 期待する値ではなく、実際の値を記録する
• ドキュメントよりもコードを信頼する
• 行き詰まったら休憩する（新鮮な目で見ると役立ちます）

---

クイックリファレンス

1. REPRODUCE → Can I reliably trigger this?
2. ISOLATE   → Where exactly is it failing?
3. DIAGNOSE  → Why is it failing?
4. FIX       → How do I fix it permanently?

---

出力テンプレート

## Bug Investigation: [Title]

### Reproduction

- Steps to reproduce
- Environment details
- Frequency

### Isolation

- Search method used
- Scope narrowed to

### Root Cause

- What's actually wrong
- Why it happens
- Evidence

### Fix

- Code changes made
- What review confirmed, and what it couldn't

### Prevention

- How to prevent similar bugs
- Documentation updates