系統的デバッグ（原因究明の規律）

大原則: 根本原因を掴む前に修正を書かない

症状を見て即座にコードを直し始めない。「たぶんここだろう」で 1 行変えて様子を見るのは、 当てずっぽうを修正と呼んでいるだけで、運良く直っても何が起きていたか分からないまま残る。 これは CLAUDE.md の「課題を後回しにしない」「一時的な修正をしない」「字面でなく意図で動く」の 実行手順版である。

時間が無いときほど、当てずっぽうのループ（変える→ダメ→また変える）が最も時間を食う。 焦ったら、むしろ系統的に進めた方が速い（「焦ったら止まれ」と接続）。

4 フェーズ

順に進める。前のフェーズを飛ばして次に行かない。

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

修正案を考える前に、まず何が起きているかをデータで掴む。

• データフローの境界（入力・分岐・外部呼び出し・出力）に計測（ログ / dump / ブレークポイント）を 仕込み、症状の出る地点から原因方向へ遡る。
• 「どこで期待と実際がズレるか」を 1 点に絞り込む。憶測でなく観測した値で語る。
• コードの呼び出し元・依存関係の遡及は serena MCP を使う （mcp__serena__find_referencing_symbols で参照元、mcp__serena__find_symbol で定義）。 grep の無計画な全文検索でなく、シンボル単位で追う（CLAUDE.md の discovery ポリシー）。 serena MCP 未導入なら、計画的な検索で代替する（無計画な grep は避ける）。

フェーズ 2: working / broken の差分比較

「動く状態」と「壊れた状態」が両方あるなら、その差分に原因がある。

• 動く入力 / 動くコミット / 動く環境と、壊れるそれを並べ、違いを 1 つずつ列挙する。
• git bisect、動く入力との比較、直前に変わった箇所（diff・最近のコミット）を確認する。
• 「差分はこれだけ」と言い切れるところまで絞る。

フェーズ 3: 単一仮説の検証

絞り込んだ原因について、仮説を文章で 1 つ書く。

• 「X だから症状 Y が出る。X を Z にすれば Y は消えるはず」と言語化する。
• 検証は 1 回に 1 変数だけ変える。複数同時に変えると、何が効いたか分からなくなる。
• 仮説が外れたら、当て直すのではなくフェーズ 1 のデータに戻る。仮説を捨てる勇気を持つ。

フェーズ 4: 失敗するテスト / 再現を先に固定してから 1 点修正

直す前に、今は失敗するテストか再現手順を用意する。

• 失敗を先に観測する（RED を見る）。失敗を見ていない修正は、正しい所を直した確証が無い。 （ブラウザ検証や既存のテスト手段（affected-area-testing 等）と接続。コードベースに応じて 自動テスト・再現スクリプト・手順のいずれでもよいが、「修正前に失敗が再現すること」を 必ず先に確認する。）
• 修正は仮説に対応する最小の 1 点に留める。ついでの整理を混ぜない。
• 修正後、用意した失敗が**通る（GREEN）**ことと、周辺が壊れていないことを確認する。

追加ルール

• 修正が 3 回失敗したら、戦術でなくアーキテクチャを疑う。 同じ箇所を 3 回直して直らないなら、原因はその行ではなく設計・前提・データモデルの側にある。 4 回目の当てずっぽうに進まず、フェーズ 1 に戻って前提ごと疑い直す。
• 原因が説明できないまま「直った」で終えない。 なぜ直ったか説明できないなら、再発する。

スタック固有の調査 skill との棲み分け

• 本 skill は言語・フレームワーク非依存の調査規律（上位）。
• スタック固有のデータ調査 skill（例: Laravel なら debug-bar-investigation の Debug Bar 3 段階調査）があれば、本 skill のフェーズ 1（計測してデータフローを遡る）の 具体手段として併用する。本 skill は手順の骨格、固有 skill はその実装にあたる。