systematic-debugging

name: systematic-debugging description: "バグや障害を体系的に調査し、エビデンスに基づいて根本原因を特定する。Use when: 「動かない」「エラーが出る」「なぜか失敗する」「原因がわからない」「デバッグしたい」「テストが落ちる」「本番で問題が起きている」「再現できない」。一般的なコードレビューにはfind-bugsを使用。"

推測ではなくエビデンスに基づいて根本原因を特定する体系的デバッグプロセス。

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

原因を特定せずに修正を試みることを禁止する。3回修正に失敗したらアーキテクチャの問題として人間にエスカレーションする。

こう思ったら	現実
「原因は多分これだから先に直す」	推測で修正するな。まず再現・証拠を取れ
「3回直しても失敗したがもう1回試す」	3回失敗はアーキテクチャの問題。人間にエスカレーション
「ログを見れば分かる」	ログは症状。根本原因は別のレイヤーにある可能性を疑え

核心原則: 仮説を立てる前に事実を集める。修正する前に原因を理解する。

まず事実を集める。推測しない。

記録する項目:
□ 何が起きているか（エラーメッセージ、スタックトレース）
□ 何が期待されていたか
□ いつから発生しているか（直近の変更との関連）
□ 再現条件（常に再現？特定条件？間欠的？）
□ 影響範囲（1ファイル？複数？全体？）

調査コマンド例:

# 直近の変更を確認
git log --oneline -10
git diff HEAD~5

# テスト失敗の詳細
# プロジェクト固有のテストコマンドを使用

症状から考えられる原因を列挙する。この時点では検証しない。

| # | 仮説 | 確信度 | 検証コスト |
|---|------|--------|----------|
| 1 | {仮説A} | 高/中/低 | 小/中/大 |
| 2 | {仮説B} | 高/中/低 | 小/中/大 |
| 3 | {仮説C} | 高/中/低 | 小/中/大 |

優先順位: 確信度が高く検証コストが低い仮説から検証する。

各仮説を1つずつ検証する。複数同時に検証しない。

検証の記録:
□ 検証した仮説: {仮説名}
□ 検証方法: {何をしたか}
□ 結果: 支持 / 棄却 / 不確定
□ 根拠: {具体的なエビデンス}

検証テクニック:

根本原因が判明したら:

修正だけでなく、同種のバグの再発を防ぐ:

□ テストが追加されたか（同じバグが再発したら検出できるか）
□ 根本原因は構造的か（他の箇所にも同じ問題が潜んでいないか）
□ ドキュメントの更新が必要か