systematic-debugging

name	systematic-debugging
description	バグ・エラー・テスト失敗・予期しない挙動・ビルド失敗に遭遇した時、修正案を出す前に使用する根本原因調査の規律。4フェーズ（根本原因調査→パターン分析→仮説検証→実装）を順守させ、症状への場当たり修正と当てずっぽうの変更連発を防ぐ。修正3回失敗でアーキテクチャ自体を疑う。境界: 原因特定後の修正実装はwriting-code、提出前のdiff確認はself-review。

Systematic Debugging

当てずっぽうの修正は時間を浪費し、新しいバグを生む。Core principle: 修正を試みる前に、必ず根本原因を特定する。症状への修正は失敗である。

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Phase 1を完了していないなら、修正を提案できない。ルールの文言をすり抜けることは、ルールの精神に違反することと同じ（「今回は事情が違うから」は成立しない）。

緊急時・「すぐ直せそう」に見える時・既に何度か修正を試した後こそ、このプロセスを使う。体系的なデバッグは、guess-and-checkの試行錯誤より速い。

The Four Phases

各フェーズを完了してから次へ進む。

Phase 1: 根本原因調査

1. エラーメッセージを精読する — スタックトレースを最後まで読む。行番号・ファイルパス・エラーコードを控える。エラーメッセージはしばしば解決策そのものを含む
2. 確実に再現する — 確実に発火させる手順を確立する。再現できないなら、修正でなくデータ収集を続ける
3. 直近の変更を確認する — git diff・最近のコミット・依存やconfigの変更・環境差分
4. 原因を一次情報で特定する — エラーの原因を公式ドキュメント（context7 / WebSearch）で確認する（グローバル規約「推測禁止・調査先行」と同一。推測での修正着手は禁止）
5. 複数コンポーネント系では境界に診断ログを仕込む — 各コンポーネント境界で入る値・出る値・環境変数の伝播を記録し、一度実行してどの層で壊れるかの証拠を取ってから、その層を調べる
6. データフローを遡る — エラーが出た場所ではなく、不正な値の発生源を突き止める（references/techniques.md の root-cause-tracing）

Phase 2: パターン分析

1. 同じコードベースで動いている類似コードを探す
2. リファレンス実装・公式サンプルがあるなら全行読む（斜め読みで「パターンだけ真似る」ことが部分理解バグを生む）
3. 動くものと壊れているものの差分をすべて列挙する（「これは関係ないはず」と決めつけない）

Phase 3: 仮説検証

1. 単一の仮説を明文化する — 「Xが根本原因だと考える。理由はY」と書き出す
2. 最小の変更で検証する — 一度に1変数。複数の修正を同時に入れない（何が効いたか切り分け不能になり、新しいバグを生む）
3. 外れたら新しい仮説を立てる。修正を上に積まない
4. 分からないなら「Xが分からない」と明言し、調査を続けるかユーザーに聞く。分かったふりをしない

Phase 4: 実装

1. 失敗するテストケースを先に作る（最小の再現。フレームワークがなければ使い捨てスクリプトでよい）
2. 単一の修正を実装する — 特定した根本原因だけを直す。「ついでの改善」やリファクタを混ぜない。修正コードは /writing-code スキルの原則に従って書く
3. 検証する — テストが通り、他のテストが壊れておらず、元の問題が実際に解消したことを確認してから完了を報告する
4. 根本原因の修正後、必要なら多層の防御を追加する（references/techniques.md の defense-in-depth）

停止条件: 修正3回失敗はアーキテクチャの問題

修正が失敗するたびに数える。3回失敗したら、4回目を試みる前に停止してアーキテクチャ自体を疑う。

兆候: 修正のたびに別の場所で新しい問題が出る / 修正に大規模リファクタが必要になる。これは外れた仮説ではなく、間違ったアーキテクチャのサイン。ユーザーと構造の議論をしてから先へ進む。

Red Flags — 内心にこれが浮かんだら停止してPhase 1へ

• 「とりあえず暫定対応で、調査は後で」
• 「試しにXを変えてみて動くか見よう」
• 「複数まとめて変えてテストを回そう」
• 「たぶんXだから、そこを直そう」
• 「完全には理解していないが、これで動くかもしれない」
• データフローを遡る前に解決策を提案している
• 「もう1回だけ修正を試したい」（既に2回以上失敗している時）

Common Rationalizations（言い訳と現実）

言い訳	現実
「単純なissueだからプロセス不要」	単純なバグにも根本原因がある。単純ならプロセスも速く終わる
「緊急なので時間がない」	体系的デバッグはguess-and-checkの試行錯誤より速い
「まず試して、ダメなら調査する」	最初の1手がその後のパターンを決める。最初から正しくやる
「複数の修正をまとめれば時間短縮」	何が効いたか切り分けられず、新しいバグを生む
「問題は見れば分かる」	症状が見えること ≠ 根本原因を理解していること
「もう1回だけ」（2回以上失敗後）	3回失敗はアーキテクチャの問題。同じ層で修正を重ねない

Gate Function — 修正を提案する前のチェック

• エラーメッセージ・スタックトレースを最後まで読んだ
• 再現手順を確立した（または再現不能と明記した）
• 原因を一次情報（公式ドキュメント・実測した証拠）で特定した
• 仮説を1文で明文化した（「Xが根本原因。理由はY」）
• 提案する変更は1つで、根本原因に対応している（症状への対処ではない）

調査を尽くしても真に環境起因・タイミング起因・外部起因の場合は、調査内容を記録した上で適切なハンドリング（リトライ・タイムアウト・エラーメッセージ・監視）を実装する。ただし「根本原因なし」の大半は調査不足である。

---

出典: obra/superpowers（MIT License）を翻案。詳細はリポジトリルートの NOTICE.md を参照。