diagnosing-bugs

バグの診断

難しいバグに立ち向かうための規律。フェーズを飛ばすのは、明確な理由を説明できるときだけ。

コードベースを探索するときは、関連モジュールの正確なメンタルモデルを得るために、プロジェクトのドキュメント（CLAUDE.md や docs/ 配下の設計メモなど、あれば）を読むこと。

フェーズ 1 — フィードバックループを作る

これがこのスキルの本体。 それ以外はすべて機械的な作業にすぎない。バグに対するタイトな pass/fail シグナル — 「_この_バグでだけ赤になる」もの — が手に入れば、原因は必ず見つかる。二分探索も、仮説検証も、計測も、すべてこのシグナルを消費するだけだ。逆にシグナルがなければ、いくらコードを眺めても救われない。

ここに不釣り合いなほどの労力をかけること。攻めろ。工夫しろ。絶対に諦めるな。

ループの作り方 — おおむねこの順で試す

1. 失敗するテスト — バグに届く継ぎ目（seam）ならどこでもいい。ユニット、統合、E2E。
2. curl / HTTP スクリプト — 起動中の開発サーバーに対して実行する。
3. CLI 実行 — フィクスチャ入力を与え、stdout を既知の正しいスナップショットと diff する。
4. ヘッドレスブラウザスクリプト（Playwright / Puppeteer）— UI を操作し、DOM・コンソール・ネットワークに対してアサートする。
5. キャプチャしたトレースの再生。 実際のリクエスト / ペイロード / イベントログをディスクに保存し、対象のコードパスに単独で流し込む。
6. 使い捨てハーネス。 システムの最小サブセット（1 サービス＋モック依存）を立ち上げ、バグのあるコードパスを関数呼び出し 1 回で叩けるようにする。
7. プロパティ / ファズループ。 「たまに出力がおかしい」系のバグなら、ランダム入力を 1000 件流して失敗パターンを探す。
8. 二分探索ハーネス。 既知の 2 つの状態（コミット、データセット、バージョン）の間でバグが発生したなら、「状態 X で起動 → 確認 → 繰り返し」を自動化して git bisect run できるようにする。
9. 差分ループ。 同じ入力を旧バージョンと新バージョン（または 2 つの設定）に流し、出力を diff する。
10. HITL（human-in-the-loop）bash スクリプト。 最終手段。人間がクリックするしかない場合は、scripts/hitl-loop.template.sh で_人間の方を_駆動し、ループの構造だけは保つ。取得した出力は自分にフィードバックさせる。

正しいフィードバックループさえ作れれば、バグは 90% 直ったも同然。

ループを締める

ループを製品として扱うこと。_とりあえずの_ループができたら、締める：

• もっと速くできないか？（セットアップのキャッシュ、無関係な初期化のスキップ、テストスコープの絞り込み）
• シグナルをもっと鋭くできないか？（「クラッシュしなかった」ではなく、具体的な症状に対してアサートする）
• もっと決定的にできないか？（時刻の固定、乱数シードの固定、ファイルシステムの分離、ネットワークの遮断）

30 秒かかる不安定なループは、ループなしと大差ない。2 秒で決定的なループはタイトだ — デバッグの超能力になる。

非決定的なバグ

目標はきれいな再現手順ではなく、再現率を上げること。トリガーを 100 回ループさせる、並列化する、負荷をかける、タイミングの窓を狭める、sleep を差し込む。再現率 50% のバグはデバッグできるが、1% では無理だ — デバッグ可能になるまで再現率を上げ続けること。

どうしてもループが作れないとき

立ち止まって、そのことを明示的に伝えること。試したことを列挙する。ユーザーには次のいずれかを依頼する：(a) 再現する環境へのアクセス、(b) キャプチャ済みの成果物（HAR ファイル、ログダンプ、コアダンプ、タイムスタンプ付き画面録画）、(c) 一時的な本番計測コードを入れる許可。ループなしで仮説立てに進んではいけない。

完了基準 — 赤になれるタイトなループ

フェーズ 1 の完了条件は、ループがタイトかつ赤になれること：1 つのコマンド — スクリプトパス、テスト実行、curl — を名指しでき、それをすでに 1 回以上実行済み（実行コマンドと出力を貼ること）で、かつ次を満たすこと：

• [ ] 赤になれる — 実際のバグのコードパスを通り、ユーザーが訴えたそのままの症状に対してアサートしている。つまり、このバグで赤になり、修正すれば緑になる。「エラーなく動いた」ではダメ — _この特定のバグを捕まえられる_必要がある。
• [ ] 決定的 — 毎回同じ判定になる（不安定なバグの場合は、上記の通り高い再現率を固定できていること）。
• [ ] 速い — 分単位ではなく秒単位。
• [ ] エージェント単独で実行可能 — 無人で回せる。人間を挟むのは scripts/hitl-loop.template.sh 経由のみ。

このコマンドが存在しないうちにコードを読んで理論を組み立てている自分に気づいたら、止まれ — いきなり仮説に飛びつくのは、このスキルがまさに防ごうとしている失敗そのものだ。 赤になれるコマンドなくして、フェーズ 2 なし。

フェーズ 2 — 再現＋最小化

ループを回す。赤になるのを見届ける — バグが姿を現す。

確認事項：

• [ ] ループが再現しているのはユーザーが説明した失敗モードである — 近くにある別の失敗ではない。違うバグ＝違う修正。
• [ ] 失敗が複数回の実行で再現する（非決定的なバグなら、デバッグに足る再現率で再現する）。
• [ ] 正確な症状（エラーメッセージ、誤った出力、遅いタイミング）を記録済みで、後のフェーズで「修正が本当にその症状を解消したか」を検証できる。

最小化

赤になったら、再現ケースを赤のままでいられる最小のシナリオまで削る。入力・呼び出し元・設定・データ・手順を1 つずつ削り、削るたびにループを回し直す — 失敗の成立に必要なものだけを残す。

なぜやるのか：最小の再現ケースはフェーズ 3 の仮説空間を縮める（疑うべき可動部が減る）し、フェーズ 5 のきれいな回帰テストになる。

残っている要素すべてが必要不可欠になったら完了 — どれか 1 つでも取り除くとループが緑になる状態。

再現と最小化の両方が済むまで先に進まないこと。

フェーズ 3 — 仮説を立てる

どれかを検証し始める前に、順位付きの仮説を 3〜5 個生成する。仮説を 1 つしか出さないと、最初に思いついたもっともらしい案に錨を下ろしてしまう。

各仮説は反証可能でなければならない：その仮説が導く予測を明文化すること。

形式：「もし <X> が原因なら、<Y を変える> とバグが消える／<Z を変える> と悪化するはずだ。」

予測を言語化できない仮説は、ただの雰囲気だ — 捨てるか、研ぎ直すこと。

検証前に、順位付きリストをユーザーに見せること。 ユーザーはドメイン知識で瞬時に順位を入れ替えられることが多い（「#3 の箇所、ちょうどデプロイしたばかりだよ」）し、すでに除外済みの仮説を知っていることもある。安いチェックポイントで大きな時間の節約になる。ただしブロックはしない — ユーザーが離席中なら自分の順位付けで進める。

フェーズ 4 — 計測する

すべてのプローブは、フェーズ 3 の特定の予測に対応していなければならない。一度に変えるのは 1 変数だけ。

ツールの優先順位：

1. デバッガ / REPL での調査 — 環境が対応していれば。ブレークポイント 1 個はログ 10 個に勝る。
2. 狙い撃ちのログ — 仮説同士を区別できる境界に置く。
3. 「全部ログに出して grep」は絶対にやらない。

デバッグログには必ず一意のプレフィックスを付ける（例：[DEBUG-a4f2]）。最後の掃除が grep 一発で済む。タグなしのログは生き残ってしまう。タグ付きのログは死ねる。

パフォーマンス分岐。 パフォーマンス劣化に対しては、ログはたいてい間違ったツールだ。代わりに：ベースライン計測（タイミングハーネス、performance.now()、プロファイラ、クエリプラン）を確立してから二分探索する。まず測り、それから直す。

フェーズ 5 — 修正＋回帰テスト

回帰テストは修正より先に書く — ただし、それにふさわしい**正しい継ぎ目（seam）**がある場合に限る。

正しい継ぎ目とは、実際のバグのパターンを、それが起きた呼び出し箇所と同じ形で再現できる場所のこと。使える継ぎ目が浅すぎる場合（複数の呼び出し元が絡むバグに単一呼び出しのテスト、バグを引き起こした連鎖を再現できないユニットテスト）、そこに置いた回帰テストは偽の安心にしかならない。

正しい継ぎ目が存在しないなら、それ自体が発見だ。 記録すること。コードベースの構造が、バグの封じ込めを妨げているということだ。次のフェーズ用にフラグを立てる。

正しい継ぎ目があるなら：

1. 最小化した再現ケースを、その継ぎ目の失敗するテストにする。
2. 失敗するのを見届ける。
3. 修正を当てる。
4. 通るのを見届ける。
5. 元の（最小化前の）シナリオに対してフェーズ 1 のフィードバックループを回し直す。

フェーズ 6 — 掃除＋振り返り

完了を宣言する前の必須項目：

• [ ] 元の再現手順で再現しなくなった（フェーズ 1 のループを回し直す）
• [ ] 回帰テストが通る（または継ぎ目が存在しないことを文書化した）
• [ ] [DEBUG-...] の計測コードをすべて除去した（プレフィックスで grep する）
• [ ] 使い捨てプロトタイプを削除した（または明確にデバッグ用と分かる場所に移した）
• [ ] 正しかった仮説をコミット / PR メッセージに明記した — 次にデバッグする人への学びになる

最後に問うこと：このバグを防げたものは何だったか？ 答えがアーキテクチャ上の変更（良いテストの継ぎ目がない、呼び出し元のもつれ、隠れた結合）を含むなら、その具体的な内容を改善提案としてユーザーに報告する。この提案は修正が入った後に行うこと — 着手前より今の方が多くの情報を持っているのだから。