dispatching-parallel-agents

並列エージェントへのタスク割り当て

概要

複数の無関係な不具合（異なるテストファイル、異なるサブシステム、異なるバグ）がある場合、それらを順番に調査すると時間がかかります。それぞれの調査は独立しており、並行して進められます。

基本原則： 現在のユーザー／リポジトリの指示で委任が許可されている場合は、独立した問題領域ごとにエージェントを1つ割り当て、ファイルやリソースの担当範囲が重複しないようにします。このガイド自体が委任の権限やモデルの上書きを許可するものではありません。

使用する場面

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}

使用する場面：

• 根本原因が異なるテストファイルで3件以上の失敗が発生している
• 複数のサブシステムがそれぞれ独立して壊れている
• ほかの問題のコンテキストがなくても各問題を理解できる
• 調査間で共有状態がない

使用しない場面：

• 不具合同士に関連がある（1つを修正するとほかも直る可能性がある）
• システム全体の状態を把握する必要がある
• エージェント同士が互いに干渉する可能性がある

手順

1. 独立した領域を特定する

問題の種類ごとに不具合を分類します。

• ファイルAのテスト：ツール承認フロー
• ファイルBのテスト：バッチ完了時の動作
• ファイルCのテスト：中断機能

各領域は独立しています。ツール承認の修正は中断テストに影響しません。

2. エージェント向けの具体的なタスクを作成する

各エージェントには、次の内容を指定します。

• 対象範囲： 1つのテストファイルまたはサブシステム
• 明確な目標： 対象のテストを合格させる
• 制約： ほかのコードは変更しない
• 期待する成果物： 調査結果と修正内容の要約

3. 並列に割り当てる

// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently

4. 確認して統合する

エージェントから結果が返ってきたら、次の作業を行います。

• 各要約を読む
• 修正が互いに競合しないことを確認する
• テストスイート全体を実行する
• すべての変更を統合する

エージェントへのプロンプトの構成

適切なエージェント向けプロンプトは、次の条件を満たします。

1. 焦点が絞られている - 問題領域が1つに明確に定まっている
2. 自己完結している - 問題の理解に必要なコンテキストがすべて含まれている
3. 出力が具体的である - エージェントに何を返してもらうかが明確である

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

よくある間違い

❌ 範囲が広すぎる： 「すべてのテストを修正して」 - エージェントが手詰まりになります
✅ 具体的： 「agent-tool-abort.test.tsを修正して」 - 対象範囲が明確です

❌ コンテキストがない： 「競合状態を修正して」 - エージェントはどこを調べればよいかわかりません
✅ コンテキストあり： エラーメッセージとテスト名を貼り付けます

❌ 制約がない： エージェントがあらゆる箇所をリファクタリングする可能性があります
✅ 制約あり： 「本番コードは変更しないでください」または「テストのみ修正してください」

❌ 出力が曖昧： 「直して」 - 何が変更されたかわかりません
✅ 具体的： 「根本原因と変更内容の要約を返してください」

使用しない場面

関連する不具合： 1つの修正でもう一方も直る可能性があるため、まず一緒に調査します
全体的なコンテキストが必要： 理解するにはシステム全体を見る必要があります
探索的なデバッグ： 何が壊れているかまだわかっていません
共有状態： エージェント同士が干渉する可能性があります（同じファイルの編集、同じリソースの使用など）

セッションでの実例

状況： 大規模なリファクタリング後、3つのファイルで6件のテストが失敗

失敗：

• agent-tool-abort.test.ts：3件の失敗（タイミングの問題）
• batch-completion-behavior.test.ts：2件の失敗（ツールが実行されない）
• tool-approval-race-conditions.test.ts：1件の失敗（実行回数 = 0）

判断： 独立した領域でした。中断ロジック、バッチ完了、競合状態はそれぞれ別の問題です。

割り当て：

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

結果：

• エージェント1：タイムアウトをイベントベースの待機に置き換え
• エージェント2：イベント構造のバグを修正（threadIdの配置が誤っていた）
• エージェント3：非同期ツールの実行完了を待つ処理を追加

統合： すべての修正は独立しており、競合もなく、テストスイート全体が成功しました。

短縮できた時間： 逐次ではなく並列に進めることで、3つの問題を同時に解決

主なメリット

1. 並列化 - 複数の調査を同時に進められます
2. 集中 - 各エージェントの対象範囲が狭く、追跡するコンテキストが少なくなります
3. 独立性 - エージェント同士が互いに干渉しません
4. 速度 - 1つの問題を解決する時間で3つの問題を解決できます

検証

エージェントから結果が返ってきたら、次の作業を行います。

1. 各要約を確認する - 何が変更されたかを把握します
2. 競合を確認する - エージェントが同じコードを編集していないか確認します
3. テストスイート全体を実行する - すべての修正が連携して機能することを確認します
4. 抜き取り確認を行う - エージェントが体系的な誤りを犯す可能性があります

実際の活用事例

デバッグセッション（2025-10-03）より:

• 3 ファイルにまたがる 6 件の失敗
• 3 つのエージェントを並行して派遣
• すべての調査を同時に完了
• すべての修正を正常に統合
• エージェントの変更間に競合はゼロ

制限事項

• このスキルは、タスクが上記の範囲に明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が欠けている場合は、停止して確認を求めてください。