bug-hunt-swarm

Bug Hunt Swarm

読み取り専用のサブエージェント4つを並列で使ってバグを調査し、その後、メインエージェントが考えられる原因を順位付けして、問題を証明または修正する最速の方法を提案します。このスキルは診断を優先します。このワークフローでは、ファイルを編集したり、修正を実装したりしないでください。

ステップ 1：バグ調査パケットを作成する

まず、調査に役立つ最小限の情報を集めます。

1. 症状
2. 期待される動作
3. 実際の動作
4. 判明している場合は再現手順
5. 影響範囲
6. ログ、スタックトレース、失敗するテスト、スクリーンショット、最近の差分、環境情報など、関連する証拠

次の順序で情報源を確認してください。

1. ユーザーからの直接の説明
2. ユーザーが提示した明示的なファイル、スタックトレース、ログ、テスト、スクリーンショット
3. バグがリグレッションのように見える場合は、現在の Git 変更または最近のリポジトリ履歴
4. 不具合の周辺にある、最小限の関連コードパスまたはサブシステム

バグ報告の情報が不十分な場合は、最小限の問題説明を推定し、まだ不明な点を示してください。

サブエージェントを起動する前に、対象箇所に最も関係するプロジェクトの指示とドキュメントを確認してください。例：

• AGENTS.md
• リポジトリのワークフロードキュメント
• 影響を受けるサブシステムのアーキテクチャ、状態、ルーティング、スキーマ、ランタイムに関するドキュメント

ステップ 2：調査範囲を定める

スウォーム向けに、簡潔な調査概要を作成します。

1. 何が壊れているように見えるか
2. まだ証明されていないこと
3. 最も関連している可能性が高いシステムの領域
4. すでに存在する証拠
5. 何を証明できれば確認とみなせるか

有用な場合は、読み取り専用の方法で証拠を集めてください。

• rg、git diff、git log、git show
• ログ、クラッシュトレース、設定の確認
• 既存のテスト実行、または最も安全で小規模な再現コマンド

このスキルでは、ファイルの編集、新たな計測処理の追加、修正の実装を行わないでください。

ステップ 3：読み取り専用の調査担当者4人を並列で起動する

並列調査が有用なほど問題が大規模または曖昧な場合は、サブエージェントを4つ起動してください。小さく明白な問題であれば、ローカルで調査してもかまいません。

すべてのサブエージェントに対して、次のことを行ってください。

• 同じバグ調査パケットと調査概要を渡す
• 読み取り専用であることを伝える
• ファイルの編集、apply_patch の実行、変更のステージングやコミット、その他の状態変更操作を禁止する
• 簡潔な調査結果のみを求める
• 仮説、裏付けとなる証拠、不足している証拠、最小限の証明手順、確信度を求める
• 一般的なコード品質のフィードバック、細かな指摘、証拠のない推測を避けるよう伝える
• 調査結果はメインエージェントにのみ送るよう伝える

次の4つの調査担当ロールを使ってください。

サブエージェント 1：再現と影響範囲の調査

不具合の正確な発生状況と境界を明らかにします。

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

1. 最も限定的で確実な発生条件
2. バグが発生または解消する条件
3. 不具合の境界における期待される動作と実際の動作
4. 影響が局所的か、複数箇所にまたがるか、決定論的か、断続的か

このサブエージェントは読み取り専用です。ファイルの編集、パッチの適用、その他のワークスペースの変更を行ってはいけません。

推奨されるサブエージェントのロール：reviewer

サブエージェント 2：コードパスと障害箇所の調査

最も可能性の高い実行経路をたどり、動作が食い違う箇所を特定します。

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

1. 状態遷移、ライフサイクルの境界、または順序の問題
2. 呼び出し元と呼び出し先の前提の不一致
3. データフローまたは制御フローの断絶
4. 不具合の原因として最も可能性が高い最小限のコード領域

このサブエージェントは読み取り専用です。ファイルの編集、パッチの適用、その他のワークスペースの変更を行ってはいけません。

推奨されるサブエージェントのロール：広範な追跡には explorer、局所的な推論を重視する場合は reviewer

サブエージェント 3: 最近の変更とリグレッションの調査

付近の履歴や変更されたコントラクトに、リグレッションの原因となりそうなものがないか探します。

以下を確認します:

1. 症状と相関する最近の差分
2. 設定、フラグ、依存関係、スキーマ、マイグレーションのドリフト
3. 複数のエントリポイントが同時に変更されるべきだったのに、部分的にしか更新されていない箇所
4. バグ報告のタイミングと一致する挙動の変更

このサブエージェントは読み取り専用です。ファイルを編集したり、パッチを適用したり、その他ワークスペースへの変更を加えてはいけません。

推奨されるサブエージェントの役割: reviewer

サブエージェント 4: 証明計画と可観測性の調査

主要な仮説を確認または棄却するための最速の方法を特定します。

以下を確認します:

1. 失敗するはずの、最小の既存テストまたは再現手順
2. 最も有用な現在のログ、トレース、メトリクス、アサーション
3. 迅速に確信度を高められる、変更を加えない最小限のコマンド
4. 不足している証拠と、大規模な混乱を招かずにそれを収集する方法

このサブエージェントは読み取り専用です。ファイルを編集したり、パッチを適用したり、その他ワークスペースへの変更を加えてはいけません。

推奨されるサブエージェントの役割: reviewer

真の原因を見つける確率を実質的に高める仮説のみを報告してください。曖昧な推測を 6 つ返すよりも、証拠に裏付けられた 2 つの理論を返すほうが優れています。

ステップ 4: ランク付けされた仮説を統合する

統合はメインエージェントが担います。サブエージェントの出力は生の調査入力として扱い、最終的な出力とはみなしません。

仮説を統合してランク付けします:

• 重複を統合する
• 弱い推測は破棄する
• 洗練さよりも証拠を優先する
• 根本原因の可能性が高いものと、単なる寄与要因を分ける
• 代替理論は、依然として妥当な場合にのみ残す

生き残った仮説を次の形に正規化します:

1. 仮説
2. 裏付けとなる証拠
3. 不足している証拠または矛盾する証拠
4. 最小の証明ステップ
5. 確信度: 高、中、低

証拠が実際のランク付けには弱すぎる場合は、その旨をはっきり伝え、代わりに主要な未解決の問いを提示してください。

ステップ 5: 明確な診断の道筋を出力する

結果を次の順序で提示します:

1. 最も可能性の高い根本原因
2. もっともらしい代替原因 (ある場合)
3. 最速の証明ステップ
4. 推奨される修正の道筋
5. 未解決の問いまたはブロッカー

修正がまだ明確でない場合は、診断が完了したふりをせず、次に取るべき証明ステップを推奨してください。

役立つ場合は、アクションを次のようにグループ化します:

• prove now
• fix next
• follow up later

このスキルの一環として修正を実装しないでください。出力は、優先順位付けされた道筋を示す読み取り専用の診断です。