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. 並列に割り当てる

Worker A: Fix agent-tool-abort.test.ts failures.
Worker B: Fix batch-completion-behavior.test.ts failures.
Worker C: Fix tool-approval-race-conditions.test.ts failures.

Start all three with the client's parallel worker capability.

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つのエージェントを並行して派遣
• すべての調査が同時に完了
• すべての修正を正常に統合
• エージェントによる変更間の競合はゼロ