dispatching-parallel-agents

Parallel Dispatch Agents

Overview

You delegate tasks to specialized agents with isolated contexts. By carefully designing their instructions and context, you ensure they stay focused and successfully complete the task. They should not inherit your session context or history—you precisely construct everything they need. This also preserves context for yourself to coordinate the work.

When you encounter multiple unrelated failures (different test files, different subsystems, different bugs), investigating them one by one wastes time. Each investigation is independent and can be done in parallel.

Core principle: Dispatch one agent per independent problem domain and let them work concurrently.

When to Use

digraph when_to_use {
    "存在多个失败?" [shape=diamond];
    "它们是否独立?" [shape=diamond];
    "单个智能体排查所有问题" [shape=box];
    "每个问题域一个智能体" [shape=box];
    "能否并行工作?" [shape=diamond];
    "顺序执行智能体" [shape=box];
    "并行分派" [shape=box];

    "存在多个失败?" -> "它们是否独立?" [label="是"];
    "它们是否独立?" -> "单个智能体排查所有问题" [label="否 - 有关联"];
    "它们是否独立?" -> "能否并行工作?" [label="是"];
    "能否并行工作?" -> "并行分派" [label="是"];
    "能否并行工作?" -> "顺序执行智能体" [label="否 - 有共享状态"];
}

Applicable scenarios:

• 3 or more test files fail due to different root causes
• Multiple subsystems fail independently
• Each problem can be understood without the context of the other problems
• No shared state between investigations

Not applicable scenarios:

• The failures are related (fixing one may fix the others)
• The complete system state needs to be understood
• The agents would interfere with each other

Pattern

1. Identify independent problem domains

Group by failure:

• File A tests: tool approval flow
• File B tests: batch completion behavior
• File C tests: abort functionality

Each problem domain is independent—fixing tool approval will not affect the abort tests.

2. Create focused agent tasks

Each agent receives:

• Clear scope: One test file or subsystem
• Clear goal: Make these tests pass
• Constraints: Do not modify other code
• Expected output: A summary of what you found and fixed

3. Dispatch in parallel

// 在 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

When the agents return:

• Read each summary
• Verify there are no conflicts between the fixes
• Run the full test suite
• Integrate all changes

Agent Prompt Structure

A good agent prompt should be:

1. Focused - one clear problem domain
2. Self-contained - includes all the context needed to understand the problem
3. With clear output requirements - what should the agent 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" - 快速工具被中止而非完成
3. "should properly track pendingToolCount" - 期望 3 个结果但得到 0 个

这些是时序/竞态条件问题。你的任务：

1. 阅读测试文件，理解每个测试验证的内容
2. 找到根因——是时序问题还是实际 bug？
3. 修复方式：
   - 用基于事件的等待替换任意超时
   - 如果发现中止实现中的 bug 则修复
   - 如果测试的是已变更的行为则调整测试期望

不要只是增加超时时间——找到真正的问题。

返回：你发现了什么以及修复了什么的总结。

Common Mistakes

Wrong approach: Too broad: "Fix all tests" - the agent will lose direction Right approach: Be specific: "Fix agent-tool-abort.test.ts" - a focused scope

Wrong approach: No context: "Fix the race condition" - the agent does not know where Right approach: Provide context: Paste the error message and test name

Wrong approach: No constraints: The agent may refactor all the code Right approach: Set constraints: "Do not modify production code" or "only fix the tests"

Wrong approach: vague output requirements: "Fix it" - you don't know what was changed Correct approach: explicit requirements: "Return a summary of the root cause and changes made"

When not to use

Relatedness failure: Fixing one may fix the others - investigate them together first Need full context: Understanding the problem requires seeing the entire system Exploratory debugging: You don't yet know what's broken Shared state: Agents will interfere with each other (editing the same file, using the same resource)

Real-world case

Scenario: After a large-scale refactor, 6 test failures appeared across 3 files

Failures:

• 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)

Decision: Independent problem domains - the abort logic, batch completion, and race conditions are each independent

Assignment:

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

Result:

• Agent 1: replaced the timeout with event-based waiting
• Agent 2: fixed the event structure bug (threadId in the wrong place)
• Agent 3: added logic to wait for asynchronous tool execution to complete

Integration: All fixes are independent, with no conflicts, and the full test suite passes

Verification

After the agents return:

1. Review each summary - understand what was changed
2. Check for conflicts - did the agents edit the same piece of code?
3. Run the full suite - verify that all fixes work together
4. Spot-check - agents may make systematic errors