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. 並列でディスパッチする

問題領域ごとに subagent ツールを1回呼び出し、すべて同じメッセージ内で（または background: true を指定して）実行して、並行して作業させます。各呼び出しは完全なサブエージェントのディスパッチです。agent、短い description、自己完結した prompt を指定します（エージェントはこの会話を参照できません）。

subagent(agent="general", description="Fix abort tests", prompt="<full self-contained task>")
subagent(agent="general", description="Fix batch tests", prompt="<full self-contained task>")
subagent(agent="general", description="Fix race tests", prompt="<full self-contained task>")

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