diagnose

Diagnose

難しいバグのための規律です。明示的に正当化できる場合だけフェーズをスキップしてください。

コードベースを探索する際は、プロジェクトのドメイン用語集を使って関連モジュールの明確なメンタルモデルを作り、触れる領域の ADR を確認してください。

フェーズ 1 — フィードバックループを構築する

これがこのスキルの本質です。 それ以外はすべて機械的な作業にすぎません。バグに対して高速・決定的・エージェントが実行可能な合否シグナルがあれば、必ず原因にたどり着けます。二分探索も、仮説検証も、計測も、すべてそのシグナルを消費するだけです。シグナルがなければ、いくらコードを眺めても救われません。

ここに不釣り合いなほどの労力を注いでください。積極的に。創造的に。決して諦めずに。

ループの構築方法 — おおよそこの順序で試す

1. 失敗するテスト — バグに到達できる継ぎ目（seam）であればどこでも。ユニット、統合、e2e。
2. Curl / HTTP スクリプト — 起動中の開発サーバーに対して実行。
3. CLI 呼び出し — フィクスチャ入力を与え、stdout を既知の正常スナップショットと差分比較。
4. ヘッドレスブラウザスクリプト（Playwright / Puppeteer）— UI を操作し、DOM/コンソール/ネットワークをアサート。
5. キャプチャしたトレースのリプレイ。 実際のネットワークリクエスト / ペイロード / イベントログをディスクに保存し、そのコードパスを単独でリプレイ。
6. 使い捨てハーネス。 システムの最小サブセット（1サービス、依存はモック）を立ち上げ、単一の関数呼び出しでバグのコードパスを実行。
7. プロパティ / ファズループ。 バグが「時々出力が間違う」種類なら、ランダム入力を1000回流して失敗モードを探す。
8. 二分探索ハーネス。 バグが2つの既知状態（コミット、データセット、バージョン）の間で出現したなら、「状態Xで起動 → チェック → 繰り返し」を自動化し、git bisect run できるようにする。
9. 差分ループ。 同じ入力を旧バージョン vs 新バージョン（または2つの設定）に通し、出力を差分比較。
10. HITL bash スクリプト。 最終手段。人間がクリックする必要がある場合、scripts/hitl-loop.template.sh で 人間を 駆動し、ループを構造化したまま保つ。キャプチャした出力がエージェントにフィードバックされる。

正しいフィードバックループを構築すれば、バグは90%修正されたも同然です。

ループそのものを改善する

ループをプロダクトとして扱ってください。何らかの ループができたら、こう問います。

• もっと速くできるか?（セットアップをキャッシュ、無関係な初期化をスキップ、テストスコープを狭める。）
• シグナルをもっと鋭くできるか?（「クラッシュしなかった」ではなく、特定の症状をアサートする。）
• もっと決定的にできるか?（時刻を固定、RNG をシード、ファイルシステムを隔離、ネットワークを凍結。）

30秒かかる不安定なループは、ループがないのとほとんど変わりません。2秒の決定的なループはデバッグの超能力です。

非決定的なバグ

目標はきれいな再現ではなく、再現率の向上です。トリガーを100回ループし、並列化し、ストレスを加え、タイミングウィンドウを狭め、sleep を注入してください。50%再現するバグはデバッグ可能ですが、1%は不可能です。デバッグ可能になるまで再現率を上げ続けてください。

どうしてもループを構築できないとき

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

信頼できるループができるまで、フェーズ 2 へ進まないでください。

フェーズ 2 — 再現

ループを実行します。バグが現れるのを観察します。

確認事項:

• ループが ユーザー の説明した失敗モードを生んでいる — たまたま近くで起きる別の失敗ではない。間違ったバグ＝間違った修正。
• 失敗が複数回の実行で再現する（非決定的なバグの場合は、デバッグに足る十分な再現率で再現する）。
• 正確な症状（エラーメッセージ、誤った出力、遅いタイミング）をキャプチャ済みで、後のフェーズで修正が実際にその症状に対処したか検証できる。

バグを再現できるまで先へ進まないでください。

フェーズ 3 — 仮説立案

いずれかを検証する前に、3〜5個の順位付けした仮説を生成してください。単一仮説の生成は、最初の尤もらしいアイデアにアンカリングしてしまいます。

各仮説は 反証可能 でなければなりません。立てる予測を明示してください。

形式: 「もし が原因なら、<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 メッセージに記述されている — 次のデバッガが学べるように

そして問います。何があればこのバグを防げたか? 答えがアーキテクチャ変更（良いテスト継ぎ目が無い、絡み合った呼び出し元、隠れた結合）を伴うなら、具体的な内容とともに /improve-codebase-architecture スキルへ引き継いでください。推奨は修正が入った 後 に行ってください。開始時よりも今のほうが多くの情報を持っています。