run-parallel-agents-feature-debug

このスキルは、実際のエージェントツールの実行を調整します。以下のルールは必ず守ってください。 1. 並列化する前に、各失敗の根本原因が共通していないことを確認してください。 2. 起動するエージェントごとに、完全なプロンプトを作成してください。新しい `subagent_type` エージェントはタスクのコンテキストを引き継ぎません。 3. 複数の `Agent(...)` ツール呼び出しを含む単一のアシスタントメッセージで、すべての並列エージェントを起動してください。 4. 独立したデバッグレーンでは `run_in_background: true` を使用し、バックグラウンド出力をポーリングしないでください。 5. コードを変更する可能性があるデバッグレーンでは、`isolation: "worktree"` を使用してください。

並列エージェント機能によるデバッグの実行

入力

• $request：任意の問題セット、失敗リスト、または この3つの失敗しているテストスイートを並列でデバッグしてください や これらのバグをエージェントに振り分けてください などのユーザーの指示。

目標

Claude Code の実際の並列エージェントランタイムを活用し、独立した失敗を並行して診断・修正します。ただし、1つの根本原因に複数の相反する調査を割り当てないようにします。

ステップ 0：候補となるデバッグレーンを特定する

失敗の対象を特定します。

• 明示されたユーザーのバグリスト
• 失敗しているテストグループ
• 壊れているサブシステム
• コンパイル、リント、実行時、パフォーマンスに関する失敗のグループ

次に、以下を判断します。

• 失敗の件数
• サブシステムの境界として考えられるもの
• 各失敗が症状か、独立した問題か
• 各レーンが計画や広範な調査ではなく、デバッグ・修正作業かどうか

以下に該当する場合は、このスキルを使用しないでください。

• 独立したレーンが3つ未満である
• 各失敗の根本原因が共通している可能性がある
• 1つの依存関係、設定値、スキーマ変更、デプロイイベントで複数の症状を説明できる
• 実行前に作業をさらに分解する必要がある

安全な分類にユーザーの確認が必要な場合のみ、AskUserQuestion を使用してください。

成功基準：独立性を判定する価値のある、具体的な候補デバッグレーンが揃っていること。

ステップ 1：独立性を確認し、共通の根本原因による落とし穴を避ける

候補となる各レーンについて、以下を確認します。

• 他のレーンと同時期に失敗が始まったか
• 同じ依存関係、設定、マイグレーション、環境、上流サービスが複数のトレースに含まれているか
• 1つの修正で複数の症状が解消される可能性があるか
• 複数のレーンが修正段階に進んだ場合、変更範囲が互いに分離されているか

以下の場合にのみ並列化してください。

• 根本原因が別々である可能性が高い
• 再現条件が各レーン内に限定されている
• 想定される修正範囲が大きく重複しない

疑いが残る場合は、まだ並列化しないでください。まず共通の根本原因を診断してください。

根本原因のヒューリスティックとフレームワーク固有の失敗パターンについては、references/debug_patterns.md を読み込んでください。 並列デバッグの成否を左右するランタイムルールについては、references/agent-runtime-semantics.md を読み込んでください。

成功基準：選択した各レーンが、診断時と修正時の両方で独立している可能性が高いこと。

ステップ 2：各デバッグレーンに適切なエージェントを割り当てる

以下の基準に基づいて、各レーンに最も適した専門エージェントを選びます。

• フレームワークと言語
• 失敗しているファイルとディレクトリ
• エラーの特徴
• レーンが実行時、テスト、ビルド、パフォーマンスのどれを対象とするか

詳しい割り当てルールと例外については、references/agent_matching_logic.md を読み込んでください。

実用上の基本方針：

• 利用可能なエージェントの中から、最も専門性の高いフレームワーク／ドメインエージェントを使用してください
• より適切なエージェントがない場合に限り、general-purpose を使用してください
• 存在しないエージェントタイプを作らないでください

成功基準：各レーンに、選定理由の妥当なデバッグエージェントが割り当てられていること。

ステップ 3：詳細なデバッグブリーフを作成する

新しい subagent_type エージェントはメインスレッドのタスクコンテキストを持たずに開始するため、各プロンプトには次の内容を含める必要があります。

• 問題の正確な説明
• 具体的なエラーまたは症状
• 判明している場合は再現手順
• 影響を受けるファイルまたはディレクトリ
• 想定される作業範囲の境界
• 成功とみなす条件
• 必須の検証コマンドまたはテスト
• そのレーンで診断のみを行うのか、診断と修正の両方を行うのか

要約よりも、実際の証拠を優先します。

• 失敗したコマンドの出力
• スタックトレースの抜粋
• 失敗したテスト名
• 影響を受けるファイルパス

実際の失敗箇所を伝えずに、「このテストスイートを修正して」のような曖昧な指示を新しいエージェントに渡してはいけません。

成功基準：各レーンのプロンプトには、新しいエージェントが基本的な追加質問をせずに診断できるだけの情報が含まれています。

ステップ 4：すべてのエージェントを並列で一括起動する

複数の Agent(...) ツール呼び出しを含む、1 つのアシスタントメッセージで、すべてのレーンを起動します。

修正可能なデバッグレーンの起動時に必須となる設定：

• subagent_type：適合するエージェントタイプ
• description：3～5 語の短い説明
• prompt：詳細なデバッグブリーフ
• run_in_background: true
• isolation: "worktree"

ランタイム固有のルール：

• ユーザーが並列デバッグを依頼した場合、複数のアシスタントメッセージに分けて起動してはいけません
• 並列実行の安全性が重要な場合、非同期実行や分離に関する対象エージェントのデフォルト設定に頼ってはいけません
• 新しい専門エージェントを起動するためのこのスキルでは、読み取り専用のフォークを使ってはいけません

これらのルールの根拠を正確に確認するには、references/agent-runtime-semantics.md を読み込んでください。

成功基準：独立したすべてのデバッグレーンが、明示的かつ安全なランタイム設定で同時に起動されています。

ステップ 5：ポーリングせずに完了結果を集約する

起動後は、重複しない調整作業を進めます。

• バックグラウンドのトランスクリプトをポーリングせず、完了通知を待ちます
• 具体的な理由があって詳細な確認が必要な場合を除き、返されたエージェントの要約を信頼します

各レーンの完了時に、次の内容を記録します。

• 状態
• 特定された根本原因
• 変更したファイル
• 検証結果
• ブロッカーまたは未解決の範囲

あるレーンが、問題は結局独立していなかったと結論づけた場合、当初のクラスタリングが妥当だったかのように扱い続けず、残りの作業を再構成します。

成功基準：不要なトランスクリプトのノイズを増やさずに、起動したすべてのレーンの結果を追跡できています。

ステップ 6：修正を検証し、競合を確認する

並列デバッグセッションを完了とする前に、次のことを確認します。

• 各レーンについて、最初に失敗したテストまたは検証コマンドを再実行します
• 元の症状が実際に解消されていることを確認します
• ファイル変更の重複や、互いに矛盾する修正がないか確認します
• あるレーンが別のレーンのサブシステムを気づかないうちに再び壊していないことを確認します

競合がある場合：

• 自動的な集約を停止します
• 重複するファイルまたは矛盾する修正を特定します
• 意図的に統合するか、ユーザーにエスカレーションします

複数のレーンが同じ根本原因にたどり着いた場合：

• そのことを明確に伝えます
• 独立した複数の成果だったかのように扱わず、結果をまとめます

成功基準：最終結果が、並列でパッチを試みたというだけでなく、実際の修正を反映しています。

ステップ 7：集約した結果を報告する

次の内容を要約します。

• 実行したデバッグレーン
• 各レーンを担当したエージェント
• レーンごとの根本原因と修正状況
• レーンごとの検証結果
• 競合、共通する根本原因、または残っているブロッカー

一部のみ成功した場合は、そのことを明確にします。元の失敗が実際に解消されたか、範囲が明確に再設定されるまで、デバッグは完了していません。

成功基準：ユーザーに、簡潔でありながら正確な並列デバッグの概要を伝えます。

ガードレール

• 真に独立したレーンが3つ未満の場合、このスキルは使用しないでください。
• 共通の根本原因がある可能性のある症状を並列化しないでください。
• 巨大な例、評価表、フレームワークの一覧をSKILL.mdにインラインで記載しないでください。
• エージェントが周囲のタスクのコンテキストを把握していると想定しないでください。
• ユーザーから明示的に求められない限り、バックグラウンドエージェントの出力をポーリングしたり、末尾まで読み進めたりしないでください。
• 明示的な起動パラメーターを指定する方が安全な場合に、エージェントのbackgroundやisolationのデフォルト設定に頼らないでください。
• disable-model-invocationを追加しないでください。このスキルは、ユーザーが並列デバッグを求めたときに引き続き利用できる状態にしてください。
• context: forkを追加しないでください。このワークフローでは、新たに起動した専門エージェントを調整します。読み取り専用のスキルフォークを調整するものではありません。
• paths:を追加しないでください。これは汎用のオーケストレーションスキルです。

参照資料を読み込むタイミング

• references/agent-runtime-semantics.md エージェントのランタイム動作に関する根拠に基づいたルールを確認する場合に使用します。新しいコンテキスト、単一メッセージでの並列起動、バックグラウンドでの動作、ワークツリーの分離、明示的なパラメーターの優先順位を扱います。

• references/debug_patterns.md 共通の根本原因に関するヒューリスティック、フレームワーク固有のエラーパターン、トリアージのガイダンスを確認する場合に使用します。

• references/agent_matching_logic.md 詳細なエージェント選定ルールや、フレームワーク固有のエッジケースを確認する場合に使用します。

出力要件

以下を報告してください。

1. 解決したデバッグレーンのセット
2. レーンごとのエージェントの割り当て
3. 起動状況
4. レーンごとの根本原因と修正状況
5. 検証結果
6. 競合、共通原因に関する発見事項、または残っている阻害要因