diagnose

診断

難しいバグに取り組むための規律です。明確な理由がある場合に限り、フェーズを省略してください。

コードベースを調査する際は、プロジェクトのドメイン用語集を参照して、関連モジュールの全体像を把握してください。また、変更対象の領域に関する ADR も確認してください。

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

これこそがスキルです。 それ以外はすべて機械的な作業です。バグに対して、高速で決定的であり、エージェントが実行できる合否判定シグナルがあれば、原因を突き止められます。二分探索、仮説検証、計測は、どれもそのシグナルを利用するだけです。シグナルがなければ、コードをどれだけ眺めても解決には至りません。

ここには、相応以上の労力を注いでください。積極的に取り組んでください。創意工夫してください。決して諦めないでください。

フィードバックループを構築する方法 — おおむね次の順に試してください

1. バグに到達できる接点での失敗するテスト — 単体テスト、統合テスト、E2E テスト。
2. 起動中の開発サーバーに対する Curl / HTTP スクリプト。
3. フィクスチャ入力を使った CLI の実行。標準出力を既知の正常なスナップショットと比較します。
4. ヘッドレスブラウザーのスクリプト（Playwright / Puppeteer） — UI を操作し、DOM／コンソール／ネットワークを検証します。
5. キャプチャしたトレースの再生。 実際のネットワークリクエスト／ペイロード／イベントログをディスクに保存し、コードパスを分離した状態で再生します。
6. 使い捨てのハーネス。 システムの最小限の構成（1 つのサービス、モック化した依存関係）を起動し、単一の関数呼び出しでバグのコードパスを実行します。
7. プロパティベーステスト／ファジングのループ。 バグが「出力がときどき間違う」場合は、ランダムな入力を 1000 件実行し、失敗のパターンを探します。
8. 二分探索用ハーネス。 既知の 2 つの状態（コミット、データセット、バージョン）の間でバグが発生した場合は、「状態 X で起動して確認し、繰り返す」を自動化し、git bisect run を実行できるようにします。
9. 差分比較ループ。 同じ入力を旧バージョンと新バージョン（または 2 つの設定）に与え、出力を比較します。
10. HITL bash スクリプト。 最終手段です。人間がクリックする必要がある場合は、scripts/hitl-loop.template.sh で その人間 を誘導し、ループが構造化された状態を保ちます。キャプチャした出力をフィードバックとして利用します。

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

ループ自体を反復的に改善する

ループをプロダクトとして扱ってください。何らかの ループを用意できたら、次の点を確認します。

• 高速化できますか？（セットアップをキャッシュする、無関係な初期化を省く、テストの対象を絞る。）
• シグナルをより明確にできますか？（「クラッシュしなかった」ではなく、具体的な症状を検証する。）
• 決定性を高められますか？（時刻を固定する、乱数シードを設定する、ファイルシステムを分離する、ネットワークを固定する。）

不安定な 30 秒のループは、ループがない状態と大差ありません。決定的な 2 秒のループは、デバッグを強力に支援します。

非決定的なバグ

目標は再現手順を完璧にすることではなく、再現率を高めることです。トリガーを 100 回繰り返し、並列化し、負荷をかけ、時間の範囲を絞り、スリープを挿入します。50% の確率で発生するバグならデバッグできますが、1% では困難です。デバッグできるようになるまで、再現率を上げ続けてください。

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

作業を止め、その旨を明確に伝えてください。試したことを列挙してください。ユーザーには、次のいずれかを依頼します。(a) バグを再現できる環境へのアクセス、(b) キャプチャした成果物（HAR ファイル、ログダンプ、コアダンプ、タイムスタンプ付きの画面録画）、または (c) 一時的な本番環境の計測を追加する許可。ループがない状態で仮説を立てて先に進んではいけません。

信頼できるループを用意できるまで、フェーズ 2 に進まないでください。

フェーズ 2 — 再現する

ループを実行し、バグが現れるのを確認してください。

次の点を確認します。

• ループによって、ユーザーが説明した失敗パターンが発生すること — 近くで起きる別の失敗ではありません。別のバグを直しても、修正にはなりません。
• 複数回の実行で失敗を再現できること（非決定的なバグの場合は、デバッグに使えるほど高い確率で再現できること）。
• 後のフェーズで修正が実際にバグに対処したか検証できるよう、症状の正確な内容（エラーメッセージ、誤った出力、遅い処理時間）を記録していること。

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

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

検証を始める前に、優先順位を付けた仮説を3～5個立てます。仮説を1つだけ立てると、最初に思いついたもっともらしい案に引きずられます。

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

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

予測を明示できない仮説は、ただの思いつきです。破棄するか、具体化してください。

検証を始める前に、優先順位付きのリストをユーザーに提示します。 ユーザーがドメイン知識に基づいてすぐに順位を変更することもあれば（「#3の変更をデプロイしたばかりです」）、すでに除外済みの仮説を知っていることもあります。手間の少ない確認で、大きな時間の節約になります。ユーザーの返答を待って作業を止めず、ユーザーが離席中なら自分の順位に基づいて進めてください。

フェーズ 4 — 計測する

各プローブは、フェーズ 3 で立てた特定の予測に対応させます。一度に変更する変数は1つだけです。

ツールの優先順位：

1. デバッガー／REPLでの調査（環境が対応している場合）。ブレークポイント1つのほうが、ログ10個より効果的です。
2. 仮説を区別できる境界に絞ったログ。
3. 「すべてをログに出してgrepする」のは避けてください。

デバッグログにはすべて、[DEBUG-a4f2]のような一意のプレフィックスを付けます。最後にプレフィックスを一度grepするだけでクリーンアップできます。タグなしのログは残りますが、タグ付きのログは削除できます。

パフォーマンスの分岐。 パフォーマンスのリグレッションでは、通常ログは適切ではありません。代わりに、ベースラインを計測し（タイミングハーネス、performance.now()、プロファイラー、クエリプランなど）、その後に二分探索します。まず計測し、修正はその後です。

フェーズ 5 — 修正とリグレッションテスト

適切なテスト箇所がある場合に限り、修正を加える前にリグレッションテストを書きます。

適切なテスト箇所とは、呼び出し元で実際に発生する本物のバグパターンをテストで再現できる場所です。利用できる箇所が浅すぎる場合（複数の呼び出し元が必要なバグに対する単一呼び出し元のテストや、バグを引き起こした呼び出しの連鎖を再現できないユニットテストなど）、そこでのリグレッションテストは誤った安心感を与えます。

適切なテスト箇所がないなら、それ自体が調査結果です。 そのことを記録してください。コードベースのアーキテクチャが、バグを再発しないように固定できない原因です。次のフェーズでこの点を指摘してください。

適切なテスト箇所がある場合：

1. 最小化した再現ケースを、その箇所で失敗するテストにします。
2. テストが失敗することを確認します。
3. 修正を適用します。
4. テストが成功することを確認します。
5. 元の（最小化していない）シナリオに対して、フェーズ 1 のフィードバックループを再実行します。

フェーズ 6 — クリーンアップと事後分析

完了を宣言する前に、以下を必ず実施します。

• 元の再現ケースでバグが再現しないことを確認する（フェーズ 1 のループを再実行）
• リグレッションテストが成功することを確認する（または適切なテスト箇所がないことを記録する）
• [DEBUG-...]の計測コードをすべて削除する（プレフィックスをgrepする）
• 使い捨てのプロトタイプを削除する（または、デバッグ用と明確に示した場所に移動する）
• 正しいと判明した仮説をコミット／PRメッセージに明記する — 次のデバッガーが学べるようにする

次に、このバグを防ぐには何が必要だったかを考えます。 その答えにアーキテクチャの変更（適切なテスト箇所がない、呼び出し元が複雑に絡み合っている、隠れた結合など）が含まれる場合は、具体的な情報を添えて/improve-codebase-architectureスキルに引き継ぎます。推奨事項を伝えるのは、修正を適用した後にしてください。作業を始めたときよりも、今のほうが多くの情報を得ています。

---

mattpocock/skills @ b843cb5 からベンダー提供 — MIT License。更新方法についてはskills/UPSTREAM-CREDITS.mdを参照してください。