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. 独立した問題領域を特定する

壊れている箇所ごとに失敗を分類します。

• ファイル 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. 抜き取り確認を行う - エージェントが体系的な誤りを犯すことがあります