parallel-execution

并行执行模式

何时加载

• 触发条件：多 Agent 任务、并发操作、启动子 Agent、并行处理独立工作
• 跳过条件：单步任务，或没有并行机会的顺序工作流

核心概念

并行执行会使用 Agent 工具同时启动多个子 Agent（在 Claude Code 2.1.63 之前名为 Task；Task 仍可作为别名使用）。子 Agent 默认在后台运行，因此 N 个任务会并发执行，大幅缩短总执行时间。

关键规则：所有 Agent 调用都必须放在同一条助手消息中，才能实现真正的并行。如果调用分散在多条消息中，它们就会依次启动。

执行流程

第 1 步：识别可并行的任务

启动之前，请确认任务彼此独立：

• 没有任务依赖其他任务的输出
• 任务针对不同的文件或方面
• 可以同时运行而不会发生冲突

第 2 步：准备动态子 Agent 提示词

为每个子 Agent 提供自定义提示词，定义其角色：

You are a [ROLE] specialist for this specific task.

Task: [CLEAR DESCRIPTION]

Context:
[RELEVANT CONTEXT ABOUT THE CODEBASE/PROJECT]

Files to work with:
[SPECIFIC FILES OR PATTERNS]

Output format:
[EXPECTED OUTPUT STRUCTURE]

Focus areas:
- [PRIORITY 1]
- [PRIORITY 2]

第 3 步：在同一条消息中启动所有任务

重要：在同一条助手消息中发出所有 Agent 调用：

I'm launching N parallel subagents:

[Agent 1]
description: "Subagent A - [brief purpose]"
prompt: "[detailed instructions for subagent A]"

[Agent 2]
description: "Subagent B - [brief purpose]"
prompt: "[detailed instructions for subagent B]"

[Agent 3]
description: "Subagent C - [brief purpose]"
prompt: "[detailed instructions for subagent C]"

对于默认仍在前台运行子 Agent 的 Claude Code 版本，请在每次调用中添加 run_in_background: true。

第 4 步：收集结果

每个子 Agent 完成后都会自动将最终结果返回到父对话中。请等待所有子 Agent 都报告结果后再进行综合；不要轮询，也不要提前开始有依赖的工作。（单独调用 TaskOutput 已弃用。）

第 5 步：综合结果

将所有子 Agent 的输出整合为统一结果：

• 合并相关发现
• 解决建议之间的冲突
• 按严重性／重要性排序
• 创建可执行的摘要

动态子 Agent 模式

模式 1：基于任务的并行化

有 N 个任务需要实现时，启动 N 个子 Agent：

Plan:
1. Implement auth module
2. Create API endpoints
3. Add database schema
4. Write unit tests
5. Update documentation

Wave 1 - spawn 3 subagents (independent of each other):
- Subagent 1: Implements auth module
- Subagent 2: Creates API endpoints
- Subagent 3: Adds database schema

Wave 2 - after wave 1 has finished (these depend on its output):
- Subagent 4: Writes unit tests
- Subagent 5: Updates documentation

模式 2：基于目录的并行化

同时分析多个目录：

Directories: src/auth, src/api, src/db

Spawn 3 subagents:
- Subagent 1: Analyzes src/auth
- Subagent 2: Analyzes src/api
- Subagent 3: Analyzes src/db

模式 3：基于视角的并行化

同时从多个角度进行审查：

Perspectives: Security, Performance, Testing, Architecture

Spawn 4 subagents:
- Subagent 1: Security review
- Subagent 2: Performance analysis
- Subagent 3: Test coverage review
- Subagent 4: Architecture assessment

任务列表集成

使用并行执行时，任务跟踪（TaskCreate／TaskUpdate，或旧版本中的 TodoWrite）会有所不同：

顺序执行：同一时间只有一个任务处于 in_progress 状态
并行执行：可以同时有多个任务处于 in_progress 状态

# Before launching parallel tasks
todos = [
  { content: "Task A", status: "in_progress" },
  { content: "Task B", status: "in_progress" },
  { content: "Task C", status: "in_progress" },
  { content: "Synthesize results", status: "pending" }
]

# As each subagent reports back, mark its task completed
todos = [
  { content: "Task A", status: "completed" },
  { content: "Task B", status: "completed" },
  { content: "Task C", status: "completed" },
  { content: "Synthesize results", status: "in_progress" }
]

何时使用并行执行

适用场景：

• 多项独立分析（代码审查、安全检查、测试）
• 处理多个彼此独立的文件
• 从不同视角进行探索性任务
• 执行不同检查的验证任务
• 由独立组件构成的功能实现

避免并行化的场景：

• 任务之间存在依赖（任务 B 需要任务 A 的输出）
• 必须按顺序执行的工作流（提交 -> 推送 -> PR）
• 多个任务会修改同一文件（存在冲突风险）
• 正确性取决于执行顺序

性能优势

方式	5 个任务，每个 30s	总时间
顺序执行	30s + 30s + 30s + 30s + 30s	~150s
并行执行	5 个任务同时运行	~30s

并行执行的速度约为顺序执行的 N 倍，其中 N 是相互独立的任务数量。

示例：功能实现

用户请求：“实现用户身份验证功能，包括登录、注册和密码重置”

协调器制定计划：

1. 实现登录端点
2. 实现注册端点
3. 实现密码重置端点
4. 添加身份验证中间件
5. 编写集成测试

并行执行：

Wave 1 - launching 4 subagents in parallel:

[Agent 1] Login endpoint implementation
[Agent 2] Registration endpoint implementation
[Agent 3] Password reset endpoint implementation
[Agent 4] Auth middleware implementation

[Results arrive as each subagent finishes]

Wave 2 - depends on wave 1:

[Agent 5] Integration test writing

[Synthesize into cohesive implementation]

故障排查

任务是按顺序运行的吗？

• 确认所有 Agent 调用都在同一条消息中
• 对于较旧版本的 Claude Code，检查每个调用是否都设置了 run_in_background: true

结果不可用？

• 每个子 Agent 完成后都会交付结果；请等待所有子 Agent 完成
• 如果子 Agent 被拒绝某项权限，可能会在未完成工作的情况下返回；请检查其报告

输出存在冲突？

• 确保任务不会修改相同的文件
• 在综合步骤中添加冲突解决机制