dispatching-parallel-agents

Dispatching Parallel Agents

Overview

When you encounter multiple unrelated failures (different test files, different subsystems, different bugs), serial investigation wastes a lot of time. These investigations are usually independent of each other and can absolutely be parallelized.

Core principles: Dispatch one agent for each independent problem domain and let them work in parallel.

When to Use

digraph when_to_use {
    "有多个失败？" [shape=diamond];
    "它们彼此独立吗？" [shape=diamond];
    "单 agent 统一排查" [shape=box];
    "每个问题域一个 agent" [shape=box];
    "能并行工作吗？" [shape=diamond];
    "改为串行派发" [shape=box];
    "并行派发" [shape=box];

"有多个失败？" -> "它们彼此独立吗？" [label="是"];
"它们彼此独立吗？" -> "单 agent 统一排查" [label="否 - 关联问题"];
"它们彼此独立吗？" -> "能并行工作吗？" [label="是"];
"能并行工作吗？" -> "并行派发" [label="是"];
"能并行工作吗？" -> "改为串行派发" [label="否 - 共享状态"];

}


**适用：**
- 3+ 个测试文件失败且 root cause 不同
- 多个子系统独立损坏
- 每个问题都能在不依赖其他问题上下文的情况下理解
- 排查之间没有共享状态

**不适用：**
- 失败高度关联（修一个可能顺带修其他）
- 必须理解全局系统状态才能判断
- agent 会互相干扰（同一文件/资源/状态）

## The Pattern

### 1) 划分独立问题域（Domain）

按“坏在哪”分组，例如：
- 文件 A 测试：tool approval 流程
- 文件 B 测试：batch completion 行为
- 文件 C 测试：abort 功能

每个 domain 彼此独立——修 tool approval 不应影响 abort 测试。

### 2) 给每个 agent 一份聚焦任务

每个 agent 都要拿到：
- **明确 scope：** 一个测试文件或一个子系统
- **清晰目标：** 让这些测试通过
- **约束：** 不要改其他无关代码
- **期望输出：** 总结你发现了什么、修了什么

### 3) 并行派发

```typescript
// 在 Claude Code / AI 环境中
Task("修复 agent-tool-abort.test.ts 的失败")
Task("修复 batch-completion-behavior.test.ts 的失败")
Task("修复 tool-approval-race-conditions.test.ts 的失败")
// 三个任务并行运行

4) Review and integrate

After the agents return:

Read the summaries one by one
Confirm the fixes do not conflict with each other
Run the full test suite
Integrate all changes

Agent Prompt structure

A good agent prompt should:

Focused: cover only one problem domain
Self-contained: include the context needed to understand the problem
Clear output: what the agent is required to return

修复 src/agents/agent-tool-abort.test.ts 中 3 个失败的测试：

1. "should abort tool with partial output capture" - 期望消息里包含 'interrupted at'
2. "should handle mixed completed and aborted tools" - fast tool 被 abort 了但期望 completed
3. "should properly track pendingToolCount" - 期望 3 个结果但拿到 0

这些看起来是 timing/race condition 问题。你的任务：

1. 阅读测试文件，理解每个测试在验证什么
2. 找 root cause：是 timing 问题还是实现 bug？
3. 修复方式（择其必要者）：
   - 用事件/状态驱动等待替换任意 timeout
   - 如果确实存在 abort 实现 bug，就修实现
   - 如果测试在验证“已改变的行为”，再调整期望

不要简单把 timeout 加大——要找到真正原因。

返回：你发现的 root cause + 你做的修改摘要。

Common Mistakes

❌ Too broad: "Fix all the tests" — the agent will get lost
✅ Specific enough: "Only fix agent-tool-abort.test.ts" — the scope is clear

❌ No context: "Fix the race condition" — it does not know where
✅ Provide context: Paste the error message and test name

❌ No constraints: the agent may make large refactors
✅ Provide constraints: "Do not change production code" or "only change tests"

❌ Vague output requirements: "Fix it" — you do not know what was changed
✅ Clear output: "Return the root cause and a summary of changes"

When NOT to Use

Failures are related: investigate them together first (fixing one may fix a whole group)
Needs global context: the complete system must be examined to understand it
Exploratory troubleshooting: you are not even sure yet where it is broken
Shared state: they will interfere with each other (changing the same file, competing for the same resource)

Real Example from Session

Scenario: After a large refactor, 6 tests across 3 files fail

Failure distribution:

agent-tool-abort.test.ts: 3 failures (timing issues)
batch-completion-behavior.test.ts: 2 failures (tools did not execute)
tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)

Assessment: 3 independent domains — abort logic / batch completion / race conditions do not depend on each other

Dispatch:

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

Results:

Agent 1: replace timeout with event-driven waiting
Agent 2: fix the event structure bug (threadId placed in the wrong position)
Agent 3: add logic to wait for asynchronous tool execution to complete

Integration: The fixes do not conflict with each other, and the full test suite is green

Time saved: Solve 3 problems in parallel, taking close to the time of solving 1 problem serially

Key Benefits

Parallelization: multiple investigations proceed simultaneously
Focus: each agent has a narrower scope and a lower burden
Independence: no interference with each other
Speed: Solve 3 problems in about the time of 1 problem

Verification