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. 並行して割り当てる

3つのサブエージェントへの割り当てを同じ応答内で行います。これらは並行して実行されます：

Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
# All three run concurrently.

1つの応答内で複数の割り当てを行うと、並列実行になります。応答ごとに1つだけ割り当てると、逐次実行になります。

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：非同期ツールの実行完了を待つ処理を追加

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

検証

エージェントから結果が返ってきたら：

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

---

ネイティブタスクの統合

構造化されたネイティブタスクで、並行して作業するエージェントを追跡します。

ディスパッチ前

構造化された説明を付けて、エージェントごとにタスクを作成します。

TaskCreate:
  subject: "[Agent assignment — concrete deliverable]"
  description: |
    **Goal:** [What this agent should produce]

    **Files:**
    - [Expected files to touch]

    **Acceptance Criteria:**
    - [ ] [Concrete criterion]

    **Verify:** [Command to verify agent's work]

    ```json:metadata
    {"files": ["expected/files"], "verifyCommand": "test command", "acceptanceCriteria": ["criterion"]}
    ```

タスク形式の完全なリファレンスについては、skills/shared/task-format-reference.md を参照してください。

進捗の監視

TaskList

完了後

TaskUpdate でタスクを完了としてマークする際は、.tasks.json も同期してください。

1. <plan-path>.tasks.json を読み取ります
2. タスクの "status" を "completed" に設定します
3. "lastUpdated" を現在の ISO タイムスタンプに設定します
4. 書き戻します

注意事項

• blockedBy は指定しません（並行処理は独立しています）
• .tasks.json の同期はコントローラーが担当します（ディスパッチされたエージェントではありません）