diagnose

診断

難しいバグに対処するための規律です。明確な理由がある場合に限り、フェーズをスキップしてください。

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

これがこのスキルの核心です。 それ以外はすべて機械的な手順です。このバグを対象にした、高速で確定的な、エージェントが実行可能な合否シグナルがあれば、原因を特定できます。二分探索、仮説検証、計測は、いずれもこのシグナルを利用するだけです。これがなければ、どれだけ長くコードを見つめても解決できません。

ここに不釣り合いなくらい労力を注いでください。積極的に取り組んでください。創造力を発揮してください。簡単に諦めないでください。

フィードバックループを構築する方法。おおよその優先順に試してください

1. バグに到達できる seam に置いた 失敗するテスト。unit、integration、e2e のいずれでもかまいません。
2. 起動中の dev server を対象とする Curl / HTTP スクリプト。
3. fixture input を使った CLI invocation。stdout を正しいとわかっている snapshot と diff します。
4. UI を操作し、DOM／console／network を検証する Headless browser script（Playwright / Puppeteer）。
5. キャプチャしたトレースを再生する。 実際の network request、payload、event log をディスクに保存し、隔離して対応する code path を再生します。
6. 使い捨てのハーネス。 システムの最小限の部分（1 つの service、mock した deps）を起動し、関数を 1 回呼び出してバグの code path を実行します。
7. プロパティ／ファズループ。 バグが「ときどき誤った出力になる」ものであれば、ランダムな入力を 1000 個実行して失敗パターンを探します。
8. 二分探索ハーネス。 既知の 2 つの状態（commit、dataset、version）の間でバグが発生する場合、「状態 X で起動、確認」を自動化して繰り返し、git bisect run できるようにします。
9. 差分ループ。 同じ入力を old-version と new-version（または 2 組の configs）で実行し、出力を diff します。
10. HITL bash script。 最後の手段です。誰かがクリックする必要がある場合は、scripts/hitl-loop.template.sh で_人間_を操作し、ループを構造化した状態に保ちます。キャプチャした出力をあなたに戻します。

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

フィードバックループ自体を反復改善する

フィードバックループを 1 つの製品として扱ってください。_何らかの_ループができたら、次のことを考えます。

• もっと速くできますか？（setup をキャッシュする、無関係な init を省略する、test scope を絞る。）
• シグナルをもっと明確にできますか？（「クラッシュしない」ではなく、具体的な症状をアサートする。）
• もっと確定的にできますか？（時間を固定する、RNG seed を固定する、filesystem を隔離する、network を凍結する。）

30 秒かかり、flaky なループは、ループがないより少し良いだけです。2 秒で確定的なループは、デバッグにおける超能力です。

非決定的なバグ

目標は完全に再現することではなく、再現率を高めることです。トリガーを 100 回ループし、並列化し、負荷をかけ、タイミングウィンドウを狭め、sleep を挿入してください。再現率 50% の flaky なバグならデバッグできますが、1% ではできません。デバッグ可能になるまで、再現率を高め続けてください。

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

作業を止め、できないことを明確に伝えてください。試した方法を列挙します。ユーザーに以下を依頼してください。（a）再現可能な環境へのアクセス、（b）キャプチャした artifact（HAR file、log dump、core dump、タイムスタンプ付き screen recording）、または（c）一時的な production instrumentation を追加する許可。ループがない状態で仮説を立て続けてはいけません。

信頼できるループができるまで、Phase 2 に進まないでください。

Phase 2 — 再現する

ループを実行し、バグが発生するのを確認します。

次の点を確認してください。

• ループが再現するのは、ユーザーが説明した failure mode であり、近くにある別の失敗ではありません。誤ったバグは誤った修正につながります。
• 失敗が複数回の実行で再現します。非決定的なバグの場合は、デバッグできるほど再現率が高くなっています。
• 正確な症状（error message、誤った出力、遅い timing）を記録しており、後のフェーズで修正によって確実に解決したかを検証できます。

バグを再現するまでは先に進まないでください。

Phase 3 — 仮説を立てる

仮説を検証する前に、優先順位を付けた仮説を 3〜5 個作成してください。仮説を 1 つだけ作ると、最初にもっともらしく見えた考えに引きずられてしまいます。

各仮説は反証可能でなければなりません。つまり、どんな予測が得られるかを示してください。

形式：「 が原因なら、 を変更するとバグが消える／ を変更すると悪化する。」

予測を示せない仮説は、ただの思いつきです。捨てるか、より具体的にしてください。

検証を始める前に、優先順位を付けたリストをユーザーに提示してください。 ユーザーは多くの場合、domain knowledge を持っており、優先順位をすぐに変更できます（「#3 の変更をデプロイしたばかりです」など）。あるいは、すでに除外された仮説を知っていることもあります。このチェックポイントはわずかな手間で時間を節約できます。ここで作業を止めないでください。ユーザーが AFK なら、付けた優先順位どおりに進めてください。

Phase 4 — 計測する

各 probe は Phase 3 の具体的な予測に対応していなければなりません。一度に変更する変数は 1 つだけです。

ツールの優先順位：

1. 環境が対応している場合は、Debugger / REPL の調査を優先してください。breakpoint 1 つは log 10 行に勝ります。
2. 仮説を見分けられる境界に、対象を絞った logを追加します。
3. 「すべてを log に出して grep する」ことは絶対にしないでください。

各 debug log には、[DEBUG-a4f2] のような一意のプレフィックスを付けてください。こうすれば、最後の削除は grep 1 回で済みます。ラベルのない log は残り、ラベル付きの log は消せます。

パフォーマンスに関する分岐。 パフォーマンスの低下には、通常 log は適しません。まず baseline measurement（timing harness、performance.now()、profiler、query plan）を確立してから、二分探索してください。修正の前に測定します。

Phase 5 — 修正と回帰テスト

ただし、適切な seam がある場合に限り、修正の前に回帰テストを書いてください。

適切な seam とは、テストが call site で実際のバグパターンを再現できることです。使える seam が浅すぎる場合（バグには複数の caller が必要なのに、テストでは caller が 1 つだけである、unit test ではバグを引き起こす経路を再現できないなど）、その場所に回帰テストを追加すると誤った安心感につながります。

適切な seam がないこと自体が発見です。 その事実を記録してください。codebase の architecture が、このバグをテストで固定する妨げになっています。次のフェーズにその情報を引き継いでください。

適切な seam がある場合：

1. minimised repro を、その seam で失敗するテストに変換します。
2. 失敗することを確認します。
3. 修正を適用します。
4. テストが通ることを確認します。
5. 元の（minimised でない）シナリオに対して、Phase 1 のフィードバックループを再実行します。

Phase 6 — クリーンアップと事後検証

完了を宣言する前に、次の作業を必ず行ってください。

• 元の repro が再現しない（Phase 1 のループを再実行）
• 回帰テストが通る（または seam がないことを記録済み）
• すべての [DEBUG-...] instrumentation を削除済み（プレフィックスを grep する）
• 使い捨ての prototype を削除済み、または debug 用として明確にラベル付けした場所に移動済み
• 最終的に正しかった仮説を commit / PR message に記載し、次にデバッグする人が学べるようにする

次に、このバグを防ぐには何ができたかを考えてください。 答えに architecture の変更（適切な test seam がない、callers が密結合している、隠れた coupling があるなど）が含まれる場合は、具体的な情報を添えて /improve-codebase-architecture skill に引き継いでください。提案は修正を適用した後に行ってください。今は、作業を始めたときよりも多くの情報が得られています。