第六章：并行 Agent 编排
并行的价值
编程中最耗时的操作往往是相互独立的：审查前端代码和审查后端代码互不依赖，运行单元测试和检查文档覆盖率也没有先后关系。
串行执行这些任务：30 分钟。 并行执行：10 分钟。
Claude Code 的并行 agent 编排让这种加速成为现实。
独立任务 vs 依赖任务
并行化的前提是任务之间相互独立。在设计并行工作流之前，先分析任务依赖关系：
前端代码审查 ─────────────────────┐
├──► 汇总报告
后端代码审查 ─────────────────────┘
（并行） （串行）
运行测试套件 ──► 分析失败原因 ──► 提交修复
（依赖前者结果）可以并行的任务特征：
- 读取不同的文件集合
- 分析代码的不同维度（性能/安全/可读性）
- 对不同的服务或模块进行操作
必须串行的任务特征：
- 下一个任务需要上一个任务的输出
- 任务会修改同一个文件（写冲突）
- 有逻辑先后关系（先构建才能测试）
基础并行模式
模式 1：直接描述并行意图
最简单的方式——直接告诉 Claude 同时做多件事：
同时对这个代码库进行三个分析：
1. 用一个 agent 扫描 src/api/ 中的安全漏洞
2. 用另一个 agent 分析 src/components/ 的性能问题
3. 用第三个 agent 检查测试覆盖率
三个都完成后，汇总结果给我看。Claude 会自动生成多个 sub-agent，并行处理，最后汇总。
模式 2：使用 /batch Skill
内置的 /batch skill 专为大规模并行改动设计：
/batch 将 src/ 目录中所有使用 class-based React 组件的文件迁移到 hooks/batch 会：
- 扫描代码库，找出所有相关文件
- 将工作分解为 5-30 个独立单元
- 展示计划，等待你确认
- 确认后，为每个单元启动独立的后台 agent（各自在 git worktree 中）
- 每个 agent 完成后自动创建 PR
模式 3：自定义并行工作流 Skill
---
name: full-review
description: 对代码库进行全方位并行审查
context: fork
agent: general-purpose
---
同时启动以下四个独立的审查任务（并行执行）：
**任务 1：安全审查**（使用 Explore agent）
扫描整个代码库的安全漏洞，关注注入、认证、数据暴露。
结果写入 /tmp/review-security.json。
**任务 2：性能审查**（使用 Explore agent）
分析潜在的性能瓶颈：N+1 查询、O(n²) 算法、不必要的重渲染。
结果写入 /tmp/review-perf.json。
**任务 3：测试覆盖率**（使用 Bash 运行测试）
运行完整测试套件，生成覆盖率报告。
结果写入 /tmp/review-coverage.json。
**任务 4：文档完整性**（使用 Explore agent）
检查公开 API 是否有完整的文档注释。
结果写入 /tmp/review-docs.json。
等所有任务完成后：
1. 读取四个结果文件
2. 生成综合报告（按严重程度排序的问题列表）
3. 删除临时文件协调模式：Lead Agent + Worker Agents
对于复杂的并行工作流，使用"主导 agent + 工作 agent"模式：
---
name: feature-implementer
description: 完整实现一个功能，自动协调前后端并行开发
tools: Read, Bash
model: opus
---
实现功能：$ARGUMENTS
## 分析阶段（串行）
首先理解需求：
1. 如果是 issue 编号，读取 issue 内容
2. 分析影响范围（哪些文件需要改动？）
3. 制定实现计划（前后端各需要什么？）
## 实现阶段（并行）
同时启动：
**前端 Agent**（general-purpose）：
- 实现 UI 组件
- 添加前端验证
- 编写前端测试
**后端 Agent**（general-purpose）：
- 实现 API 端点
- 添加数据库逻辑
- 编写后端测试
**文档 Agent**（Explore）：
- 更新 API 文档
- 更新 README（如有变更）
## 集成阶段（串行，等待并行完成）
1. 检查前后端接口是否对齐（请求/响应格式）
2. 运行集成测试
3. 修复任何接口不一致
## 提交阶段
创建包含所有改动的 PR。监控后台 Agent
使用 /tasks 命令
/tasks显示所有后台任务：
- 任务名称和状态（运行中/完成/失败）
- 已消耗时间
- 最后一次活动
实时输出
后台 agent 的输出不会显示在前台，但会记录到 session 文件。要实时查看某个 agent 的进度，可以用 /tasks 找到它，或者在任务完成后查看汇总结果。
Ctrl+B 推入后台
当一个长任务正在前台运行时（比如 Claude 正在生成大量代码），可以按 Ctrl+B 推入后台，让你继续其他工作：
# Claude 正在前台实现一个复杂功能...
# 按 Ctrl+B → 任务进入后台
# 你可以开始新的对话，做其他事情
# 前台任务继续运行，完成后会通知你处理 Agent 失败
失败的类型
权限失败：后台 agent 遇到需要额外权限的操作，自动拒绝。
处理方式：在前台恢复，给予需要的权限
恢复之前的 refactor agent，这次允许它修改 package.json逻辑失败：agent 无法完成任务（文件不存在、命令失败等）。
处理方式：agent 会报告失败原因，你可以决定如何继续。
超时：agent 超过 maxTurns 限制。
处理方式：减少 scope，或增加 maxTurns：
maxTurns: 50 # 默认通常是 20错误隔离
并行 agent 互相隔离——一个 agent 失败不会影响其他 agent。这是并行化的重要优势：
三个 agent 同时运行：
- agent-1 成功完成
- agent-2 失败（权限不足）
- agent-3 成功完成
汇总时处理 agent-2 的失败，不影响 agent-1 和 agent-3 的结果。实战：大型功能实现
场景：为电商平台添加"优惠券"功能
这个功能涉及数据库、API、前端、测试多个层面。并行化可以大幅缩短时间。
第一步：分析（串行）
分析在 acme-shop 项目中添加优惠券功能需要的改动范围，
列出需要新建或修改的文件，制定实现顺序。第二步：并行实现
基于上面的分析，同时启动三个 agent 并行实现：
Agent A（数据库层）：
- 创建 coupons 表的迁移文件
- 在 Order 模型中添加 coupon_code 字段
- 实现 CouponRepository（CRUD + 验证逻辑）
- 编写数据层单元测试
Agent B（API 层）：
- POST /api/coupons（创建优惠券）
- GET /api/coupons/:code（验证优惠券）
- POST /api/orders/apply-coupon（应用优惠券）
- 编写 API 测试
（依赖：Agent A 的接口定义）
Agent C（前端）：
- 在结账页面添加优惠券输入框
- 调用 API 验证并展示折扣
- 处理错误状态（无效码、已使用等）
- 编写前端测试
注意：Agent B 依赖 Agent A 的数据模型接口，
如果 Agent A 还未完成，Agent B 先实现接口定义，等待 Agent A 的实现。第三步：集成验证（串行）
所有 agent 完成后：
1. 运行完整测试套件
2. 手动检查数据库 → API → 前端的数据流
3. 修复任何发现的接口不一致
4. 创建 PR性能与成本计算
时间节省
假设各部分工作量：
- 数据库层：20 分钟
- API 层：25 分钟
- 前端：20 分钟
- 集成测试：10 分钟
串行：75 分钟 并行：max(20, 25, 20) + 10 = 35 分钟 节省：54%
Token 成本
并行 agent 各自消耗 token，总 token 量约等于串行。时间节省了，成本基本不变。
对于 API 用户，并行 agent 可能略微增加成本（每个 agent 有启动开销），但对于按 session 计费的 Pro/Max 用户，成本不变而时间大幅缩短，性价比极高。
并行 vs 顺序：决策树
任务是否可以拆分成独立部分？
├── 否 → 单 agent 顺序执行
└── 是 → 子任务会修改同一文件吗？
├── 是 → 需要 worktree 隔离 (isolation: worktree)
└── 否 → 直接并行
└── 任务量大（>5 个文件）？
├── 是 → 考虑 /batch
└── 否 → 直接描述并行意图本章总结
并行 agent 的核心价值是把串行工作的"时间成本"转换为"空间成本"——多个 agent 同时工作，各占一份上下文，但总耗时大幅减少。
关键原则：
- 先分析依赖，再决定哪些可以并行
- 用 /batch 处理大规模改动（5+ 个独立文件）
- Ctrl+B 推后台，不要让长任务阻塞你的工作
- 设计好汇总阶段，并行结果需要人工或 agent 整合
下一章，我们看大项目中的经典工作流：Architect → Coders → Review。
下一章： 大项目模式