Chapter 9: Agent 团队 — 真正能交付的并行工作流
你将构建什么
两个来自生产代码库的真实并行工作流：
- Autoplan 审查管线 — 三个 Agent 分别从产品、设计、工程角度审查，然后综合（来自 gstack 的 CEO/Design/Eng 管线）
- 并行功能开发 — 前端 + 后端 + 测试同时由独立 Agent 构建，支持依赖感知编排
这些模式来自 gstack（68k 星）和 ECC 的 dmux-workflows。它们是真实团队使用 Claude Code 并行化开发的方式。
附录链接：A13 多 Agent 协调 涵盖共识协议、冲突解决策略，以及 5 个以上 Agent 的扩展模式。
研究笔记：本章的编排者-工作者（Orchestrator-Worker）和并行化模式在 Anthropic 的 Building effective agents 指南中有形式化描述。该指南确定了五种关键的多 Agent 模式；本章聚焦其中两种：并行委派（Demo 24）和依赖感知编排（Demo 25）。
Agent 团队工作原理
在第 8 章，你使用了 Subagent — 为特定任务启动的单个 Agent，将结果返回主会话。Agent 团队更进一步：多个 Agent 并行运行，每个拥有自己的会话，能够互相通信。
Lead（你的 Claude 会话）
|
+---> Agent A（前端） --|
| 独立会话 | 并行运行
| 独立 200K 上下文 | 每个完全独立
| |
+---> Agent B（后端） --|
| 独立会话 |
| 独立 200K 上下文 |
| |
+---> Agent C（测试） --| 等待 A 和 B
独立会话
独立 200K 上下文
|
<--- Lead 收集所有结果，综合输出团队 vs Subagent
| Subagent (Ch8) | Agent 团队 (Ch9) | |
|---|---|---|
| 会话 | 共享主会话的进程 | 每个成员获得独立会话 |
| 通信 | 只向主会话返回结果 | 成员间可互相发消息 |
| 生命周期 | 一个任务完成即结束 | 可以接多个任务 |
| 适合 | 聚焦的分析任务 | 并行开发工作 |
| 显示 | 内联在主会话中 | tmux 面板或交错输出 |
GSD 的 Wave 执行模型
GSD（50k 星）将此形式化为"Wave Execution"：并行任务在全新的 200K 上下文中运行。每个 Agent 获得干净的上下文窗口（Context Window），避免"Context Rot"问题——即上下文使用超过 50% 后质量下降。
关键洞察：一个全新的 200K 上下文产出的代码比一个被污染的 150K 上下文更好，即使全新的上下文历史更少。这就是为什么在大型任务中并行 Agent 优于单会话串行工作。
通信：Mailbox 系统
成员通过 Mailbox 通信：
前端 Agent --> 后端 Agent: "POST /api/tasks 的响应格式是什么？"
后端 Agent --> 前端 Agent: "{ id: string, title: string, status: 'pending' | 'done', createdAt: ISO8601 }"
前端 Agent: "收到，正在构建类型接口"当某个 Agent 需要另一个 Agent 的信息时，这会自动发生。Lead（你的会话）也可以向任何成员发消息。
任务依赖
任务可以有依赖关系：
Task 1: 构建 API 端点 (无依赖) --> Agent B
Task 2: 构建 UI 组件 (无依赖) --> Agent A
Task 3: 写集成测试 (需要 1 + 2) --> Agent C（等待）
Task 4: 写部署配置 (需要 3) --> Agent A（之后）系统自动并行运行 1 和 2，两者完成后启动 3，3 完成后执行 4。
Demo 24: Autoplan 审查管线
24
Multi-Perspective Review Pipeline
Intermediate~20 min
改编自 gstack 的 CEO -> Design -> Eng 审查管线和"Boil the Lake"完整度方法论。
问题
一个功能规格或 PR 提交了。在好的团队中，它会从多个角度被审查——产品（这值得做吗？）、设计（UX 对吗？）、工程（架构合理吗？）。通常需要 3 个不同的人和一天的日历时间。用 Agent 团队，你在 2 分钟内获得所有三个视角。
构建
1. 准备
bash
mkdir -p ~/claude-demos/demo-24/src && cd ~/claude-demos/demo-24
git init && git branch -M main
# 一个待审查的功能：任务管理 API
cat > src/task-service.js << 'EOF'
import { db } from './db.js';
import { sendNotification } from './notify.js';
export class TaskService {
async createTask(req, res) {
const { title, description, assigneeId, priority, dueDate } = req.body;
// No validation on priority range
// No check if assigneeId exists
const task = await db.query(
`INSERT INTO tasks (title, description, assignee_id, priority, due_date, status)
VALUES ($1, $2, $3, $4, $5, 'pending') RETURNING *`,
[title, description, assigneeId, priority, dueDate]
);
// Fire and forget — if notification fails, user never knows
sendNotification(assigneeId, `New task: ${title}`).catch(() => {});
return res.status(201).json(task.rows[0]);
}
async listTasks(req, res) {
const { status, assignee, sort } = req.query;
// Building query dynamically — but safely with parameterized queries
let query = 'SELECT * FROM tasks WHERE 1=1';
const params = [];
let paramCount = 0;
if (status) { paramCount++; query += ` AND status = $${paramCount}`; params.push(status); }
if (assignee) { paramCount++; query += ` AND assignee_id = $${paramCount}`; params.push(assignee); }
// No pagination — will return ALL tasks
query += ` ORDER BY ${sort || 'created_at'} DESC`;
const result = await db.query(query, params);
return res.json(result.rows);
}
async updateStatus(req, res) {
const { id } = req.params;
const { status } = req.body;
// No validation on status values
// No check if task exists
// No authorization — anyone can update any task
await db.query('UPDATE tasks SET status = $1, updated_at = NOW() WHERE id = $2', [status, id]);
return res.json({ success: true });
}
async deleteTask(req, res) {
const { id } = req.params;
// Hard delete — no soft delete, no audit trail
await db.query('DELETE FROM tasks WHERE id = $1', [id]);
return res.json({ success: true });
}
}
EOF
# 功能规格文档
cat > FEATURE_SPEC.md << 'EOF'
# Feature: Task Management System
## User Story
As a team member, I want to create, assign, and track tasks so that our team can coordinate work effectively.
## Requirements
- Create tasks with title, description, assignee, priority (1-5), and due date
- List tasks with filtering by status and assignee
- Update task status (pending -> in_progress -> done)
- Delete tasks
- Notify assignees when tasks are created
## Technical Notes
- REST API using Express
- PostgreSQL database
- Notification via internal service
EOF
cat > CLAUDE.md << 'EOF'
# Task Management API
- Node.js + Express + PostgreSQL
- Parameterized queries for SQL
- RESTful conventions
EOF
git add -A && git commit -m "feat: task management API and feature spec"2. 创建三个审查 Agent
bash
mkdir -p .claude/agents
# 产品（CEO）审查 Agent
cat > .claude/agents/product-reviewer.md << 'EOF'
---
name: product-reviewer
description: Reviews from a product/business perspective — is this worth building?
tools:
- Read
- Glob
- Grep
model: claude-sonnet-4-6
---
You are a product manager reviewing a feature implementation. Your job is to evaluate whether this feature delivers real value and is ready to ship to users.
## Review Criteria
### Value Assessment
- Does the implementation match what users actually need?
- Are there missing capabilities that would make this useless? (e.g., can create tasks but can't set due dates)
- What's the minimum viable version of this feature?
### User Experience Gaps
- What happens when things go wrong? (error messages, edge cases)
- Is the API intuitive? Would a developer integrating this be confused?
- Are there missing features that users would immediately ask for?
### Business Risk
- Could this cause data loss?
- Could this cause customer-facing outages?
- Is there anything that would block a launch?
## Output FormatProduct Review
Verdict: SHIP / ITERATE / BLOCK
Completeness Rating: X/10
(gstack's "Boil the Lake" score — how complete is this feature?)
What Works
- [Things the implementation gets right]
Gaps
- [P0] [Missing capability that blocks ship]
- [P1] [Missing capability that hurts adoption]
- [P2] [Nice-to-have for v2]
User Impact Assessment
- Who benefits from this feature?
- What workflow does it enable?
- What's missing for the workflow to actually work end-to-end?
EOF
# 设计审查 Agent
cat > .claude/agents/design-reviewer.md << 'EOF'
---
name: design-reviewer
description: Reviews API design, UX patterns, and developer experience
tools:
- Read
- Glob
- Grep
model: claude-sonnet-4-6
---
You are a senior API designer reviewing an implementation for usability, consistency, and developer experience.
## Review Criteria
### API Design
- Are endpoints RESTful and consistent?
- Are HTTP status codes correct? (201 for create, 404 for not found, etc.)
- Are error responses structured and helpful?
- Is the request/response format consistent across endpoints?
### Developer Experience
- Could someone use this API without reading the source code?
- Are required vs optional fields clear?
- Is pagination supported for list endpoints?
- Are there reasonable defaults?
### Consistency
- Do naming conventions match across endpoints? (camelCase vs snake_case)
- Are similar operations handled the same way?
- Does the API follow the principle of least surprise?
## Output FormatDesign Review
Verdict: APPROVE / REQUEST CHANGES
API Consistency Score: X/10
Findings
- [P1] [Issue with specific recommendation]
- [P2] [Issue with specific recommendation]
Suggested API Contract
[For any endpoint with issues, show the correct request/response format]
EOF
# 工程审查 Agent
cat > .claude/agents/eng-reviewer.md << 'EOF'
---
name: eng-reviewer
description: Reviews architecture, security, performance, and code quality
tools:
- Read
- Glob
- Grep
model: claude-sonnet-4-6
---
You are a senior engineer reviewing code for production readiness. Focus on things that cause incidents.
## Review Criteria
### Security (P0)
- SQL injection (even with parameterized queries, check for string interpolation)
- Missing authentication or authorization
- Missing input validation
- Data exposure in responses
### Reliability (P1)
- Missing error handling
- Silent failures (catch-and-ignore patterns)
- Race conditions
- Missing transactions for multi-step operations
### Performance (P1)
- N+1 queries
- Missing pagination
- Missing caching for hot paths
- Unbounded query results
### Code Quality (P2)
- Missing input validation
- Hardcoded values that should be configurable
- Missing logging/observability
- Dead code or unreachable branches
## Output FormatEngineering Review
Verdict: APPROVE / REQUEST CHANGES / BLOCK
Findings
[P0] [Title]
- File: path:line
- Confidence: N%
- Problem: [What's wrong]
- Fix: [Exact code change]
[P1] [Title]
...
Architecture Notes
[Any structural concerns or recommendations]
Effort Estimate
- Critical fixes: ~Xh
- Full recommendations: ~Xh (gstack's human-vs-CC effort comparison)
EOF3. 运行管线
bash
claude我需要对任务管理功能进行全面审查。
并行运行 product-reviewer、design-reviewer 和 eng-reviewer agent，
审查 src/task-service.js 和 FEATURE_SPEC.md，
然后将发现综合为一个可执行的审查报告。4. 预期终端输出
terminal
$ claude
> 我需要对任务管理功能进行全面审查。并行运行 product-reviewer、
design-reviewer 和 eng-reviewer agent，审查 src/task-service.js
和 FEATURE_SPEC.md，然后将发现综合为一个可执行的审查报告。
Claude: 我将同时启动三个审查 agent，然后综合它们的发现。
并行启动 3 个 agent...
[product-reviewer] 启动中 (claude-sonnet-4-6, 只读)
[design-reviewer] 启动中 (claude-sonnet-4-6, 只读)
[eng-reviewer] 启动中 (claude-sonnet-4-6, 只读)
[product-reviewer] Read: FEATURE_SPEC.md
[design-reviewer] Read: src/task-service.js
[eng-reviewer] Read: src/task-service.js
[product-reviewer] Read: src/task-service.js
[design-reviewer] Read: FEATURE_SPEC.md
[eng-reviewer] Grep: 'req.body' in src/ -> 3 matches
[eng-reviewer] Grep: 'req.params' in src/ -> 2 matches
[eng-reviewer] Grep: 'req.query' in src/ -> 1 match
[product-reviewer] 完成。(2.1s)
[design-reviewer] 完成。(1.8s)
[eng-reviewer] 完成。(2.4s)
全部 3 个 agent 完成。正在综合结果...
---
# 综合审查报告
## 总体结论：ITERATE（目前不应发布）
## 产品审查（结论：ITERATE，完整度：6/10）
### 做得好的
- 核心 CRUD 操作已实现
- 参数化 SQL 查询（安全基础扎实）
- 创建任务时发送通知
### 缺口
- [P0] 没办法列出"我的任务"——虽然有 assignee 过滤，
但没有认证上下文来默认当前用户
- [P1] 没有任务重新分配——一旦分配就固定了
- [P1] deleteTask 没有确认或撤销——数据丢失风险
- [P2] 没有截止日期提醒或逾期指示器
## 设计审查（结论：REQUEST CHANGES，一致性：4/10）
### 发现
- [P1] 响应不一致：createTask 返回完整任务对象，
updateStatus 返回 {success: true}，deleteTask 返回 {success: true}。
所有变更操作应返回受影响的资源。
- [P1] listTasks 没有分页——超过 1000 个任务时会崩溃。
添加 ?page=1&limit=20 和 Link 头。
- [P2] 命名混合：assignee_id（数据库中 snake_case）vs assigneeId
（API 中 camelCase）。API 层应统一一种风格。
## 工程审查（结论：BLOCK，关键修复约 3 小时）
### [P0] sort 参数导致 SQL 注入（95% 置信度）
- 文件：src/task-service.js:28
- sort 查询参数被直接拼入 SQL：
ORDER BY ${sort || 'created_at'} DESC
- PoC：GET /api/tasks?sort=created_at;DROP TABLE tasks;--
- 修复：白名单限制允许的排序列
### [P1] updateStatus 缺失授权（90% 置信度）
- 文件：src/task-service.js:36
- 任何已认证用户都可以更新任何任务的状态
- 没有所有权或角色检查
### [P1] 通知静默失败（88% 置信度）
- 文件：src/task-service.js:16
- sendNotification 的失败被捕获后丢弃
- 用户永远不会被告知通知未送达
## 优先级行动计划
1. 立即修复：白名单排序列以防止 SQL 注入（约 30 分钟）
2. 立即修复：为 updateStatus 添加授权检查（约 1 小时）
3. 发布前：为 listTasks 添加分页（约 2 小时）
4. 发布前：统一所有端点的响应格式（约 1 小时）
5. 下一迭代：添加任务重新分配和截止日期提醒
总关键工作量：约 3.5 小时（不用 Claude Code 预计约 1 天）刚才发生了什么？
1
TaskAgent (x3)
product-reviewer, design-reviewer, eng-reviewer
↓
2
Read (parallel)
src/task-service.js + FEATURE_SPEC.md
↓
3
Grep (eng only)
User input patterns
↓
4
Synthesize
Lead session
三个 Agent 并行运行，总共约 2.4 秒完成（不是 2.4 x 3 = 7.2 秒）。每个从自己的视角发现不同的问题：产品审查员发现了缺失的"我的任务"流程，设计审查员发现了不一致的响应格式，工程审查员发现了 SQL 注入。没有任何单个 Agent 能同时捕获所有三个类别的问题。
为什么这个模式有效
这是 gstack 的"Boil the Lake"方法：从每个角度审查，直到完整度评分达到 9+/10。每个审查员捕获不同的问题：
- 产品："这个功能不完整——任务分配通知实际上不起作用"
- 设计："API 不一致——createTask 返回对象，updateStatus 返回
{success: true}" - 工程："
sort参数被直接拼入 SQL——这是 P0"
没有任何单个审查员能同时捕获所有三个。并行执行意味着你用运行一个的时间获得了所有视角。
Demo 25: 并行功能开发
25
Parallel Feature Development with Dependency Orchestration
Intermediate~25 min
改编自 ECC 的 dmux-workflows 和 GSD 的 Wave Execution 模式。
问题
你需要构建一个跨前端、后端和测试的功能。在单个 Claude 会话中串行做意味着上下文很快填满，在关注点之间切换时质量下降。并行 Agent 每个获得全新的 200K 上下文，专注于一件事。
构建
1. 准备
bash
mkdir -p ~/claude-demos/demo-25/{src/api,src/pages,tests} && cd ~/claude-demos/demo-25
git init && git branch -M main
cat > CLAUDE.md << 'EOF'
# Bookmark Manager
## Tech Stack
- Backend: Node.js + Express + PostgreSQL
- Frontend: Vanilla HTML + JavaScript (no framework)
- Testing: Vitest
## Feature: Bookmark CRUD
Users can save, list, tag, and search bookmarks.
## API Contract
POST /api/bookmarks
Body: { url: string, title: string, tags: string[] }
Response: { id, url, title, tags, createdAt }
GET /api/bookmarks?tag=&search=
Response: { bookmarks: [...], total: number }
DELETE /api/bookmarks/:id
Response: { success: true }
## Coding Standards
- Use parameterized SQL queries
- Validate all input
- Return appropriate HTTP status codes
- Tests must mock the database layer
EOF
cat > src/api/index.js << 'EOF'
import express from 'express';
const app = express();
app.use(express.json());
app.use(express.static('src/pages'));
// Routes will be added by the backend agent
export default app;
EOF
cat > package.json << 'EOF'
{
"name": "bookmark-manager",
"version": "1.0.0",
"type": "module",
"scripts": {
"start": "node src/api/index.js",
"test": "vitest run"
},
"dependencies": {
"express": "^4.18.0"
},
"devDependencies": {
"vitest": "^1.0.0"
}
}
EOF
git add -A && git commit -m "feat: project skeleton with API contract"2. 启动并行开发
bash
claude使用并行 agent 构建书签管理器功能：
1. 后端 Agent：在 src/api/bookmarks.js 中实现 API 端点，
遵循 CLAUDE.md 中的契约。连接 src/api/index.js 中的路由。
聚焦：输入验证、参数化查询、错误处理、正确的状态码。
2. 前端 Agent：构建 src/pages/index.html — 单页应用，包含：
- 添加书签表单（URL、标题、标签）
- 书签列表，支持标签过滤
- 搜索框
- 每个书签的删除按钮
- 简洁、实用的设计（无需框架，原生 JS 即可）
3. 测试 Agent：后端 Agent 完成后，
在 tests/bookmarks.test.js 中编写测试，覆盖：
- 每个端点的正常路径
- 验证失败（缺少 URL、无效输入）
- 边界情况（重复书签、空搜索结果）
Mock 数据库层。
后端和前端 agent 并行运行。后端完成后启动测试 agent。3. 预期终端输出
terminal
$ claude
> 使用并行 agent 构建书签管理器功能...
Claude: 我将使用依赖感知调度编排三个 agent：
- 后端和前端并行运行（无依赖）
- 测试 agent 在后端完成后启动（需要 API 代码来测试）
任务图：
[Backend] ----+---> [Test Agent]
[Frontend] ----+
启动后端 agent...
启动前端 agent...
[Backend] Read: CLAUDE.md (API 契约)
[Frontend] Read: CLAUDE.md (API 契约)
[Backend] Read: src/api/index.js (入口文件)
[Frontend] Write: src/pages/index.html (创建 SPA)
[Backend] Write: src/api/bookmarks.js (3 个端点)
[Frontend] 添加 POST、GET、DELETE 的 fetch 调用...
[Backend] Edit: src/api/index.js (连接路由)
[Frontend] 添加标签过滤下拉框和搜索输入框...
[Backend] 完成。3 个端点含验证。(3.2s)
后端完成。启动测试 agent...
[Frontend] 添加带确认的删除按钮...
[Test] Read: src/api/bookmarks.js (理解 API)
[Test] Read: package.json (检测 vitest)
[Frontend] 完成。带搜索和过滤的单页应用。(4.1s)
[Test] Write: tests/bookmarks.test.js (14 个测试用例)
[Test] Bash: npx vitest run --reporter=verbose
stdout | tests/bookmarks.test.js
POST /api/bookmarks
+ creates bookmark with valid input (2ms)
+ returns 400 when URL is missing (1ms)
+ returns 400 when URL format is invalid (1ms)
+ stores tags as array (1ms)
+ returns 201 with created bookmark (1ms)
GET /api/bookmarks
+ returns all bookmarks with total count (2ms)
+ filters by tag when tag parameter provided (1ms)
+ searches title and URL when search parameter provided (1ms)
+ returns empty array when no matches (1ms)
+ handles pagination parameters (1ms)
DELETE /api/bookmarks/:id
+ deletes existing bookmark (1ms)
+ returns 404 for non-existent bookmark (1ms)
+ returns success true on deletion (1ms)
Edge cases
+ handles special characters in search query (2ms)
Test Files 1 passed (1)
Tests 14 passed (14)
Duration 0.28s
[Test] 完成。14/14 测试通过。(2.8s)
全部 agent 完成。总耗时：6.0s（串行约需 18s）
创建的文件：
src/api/bookmarks.js (带验证的 API 端点)
src/pages/index.html (带搜索/过滤/删除的单页应用)
tests/bookmarks.test.js (14 个测试用例，全部通过)
修改的文件：
src/api/index.js (已添加路由注册)刚才发生了什么？
1
Plan
Task dependency graph
↓
2
TaskAgent (x2)
Backend + Frontend agents
↓
3
Write (Backend)
src/api/bookmarks.js + index.js
↓
4
Write (Frontend)
src/pages/index.html
↓
5
TaskAgent
Test agent (wave 2)
↓
6
Write + Bash (Test)
tests/bookmarks.test.js
CLAUDE.md 文件充当了 Agent 之间的共享契约。后端和前端 Agent 从未直接通信——它们都读取了 API 契约并按规格构建。这就是"共享产物"协调模式（Shared Artifact）：Agent 不需要互相对话，而是就一个接口文档达成一致。
4. 验证
bash
# 检查所有文件是否已创建
ls src/api/bookmarks.js src/pages/index.html tests/bookmarks.test.js
# 运行测试
npm test
# 启动服务器并手动检查
node src/api/index.js &
# 在浏览器中打开 http://localhost:3000如何映射到 GSD 的 6 步流程
GSD 的流程是：Initialize -> Discuss -> Plan -> Execute -> Verify -> Ship
在本 Demo 中：
- Initialize：CLAUDE.md 定义项目和 API 契约
- Discuss：Prompt 定义每个 Agent 的需求
- Plan：Claude（Lead）创建任务依赖图
- Execute：三个 Agent 并行运行（Wave Execution）
- Verify：测试 Agent 运行测试，Lead 检查结果
- Ship：所有文件创建完成，测试通过，准备部署
GSD 的关键洞察：每个 Agent 获得全新的 200K 上下文（"wave"），即使总工作量增大，质量也保持高水平。单个会话串行完成所有三个任务，到测试阶段时上下文已用到 60% 以上，产出质量更差。
出错时怎么办
Agent 通信超时
terminal
$ claude
> 用前端和后端 agent 构建一个功能。前端需要知道后端的
精确响应 schema。
Claude: 正在并行启动后端和前端 agent...
[Frontend] 构建表单组件...
[Frontend] --> Backend: POST /api/items 返回什么字段？
[Frontend] 等待后端 agent 响应...
[Backend] 还在实现输入验证...
[Backend] 还在写数据库查询...
[Frontend] 等待后端响应超时 (30s)。
[Frontend] 回退到 CLAUDE.md 契约定义。
[Frontend] 使用规格中的 { id, name, createdAt }。
[Frontend] 完成。
[Backend] 完成。POST /api/items 返回 { id, name, description,
createdAt, updatedAt }
警告：前端基于规格契约构建，但后端返回了规格中没有的
额外字段（description, updatedAt）。发生了什么：前端 Agent 向后端 Agent 询问响应 schema，但后端 Agent 正在忙碌，未能及时响应。前端回退到 CLAUDE.md 契约，而该契约不够完整。
修复方法：根本原因是 CLAUDE.md 中的 API 契约不够详细。最好的预防措施是编写详尽的共享契约，让两个 Agent 都能独立依赖，无需在运行时通信。更新 CLAUDE.md 以包含所有响应字段：
markdown
## API Contract
POST /api/items
Body: { name: string, description: string }
Response: { id: string, name: string, description: string, createdAt: ISO8601, updatedAt: ISO8601 }当 Agent 共享一份完整的契约时，它们就不需要实时通信。这比基于 Mailbox 的协调更可靠。
并行 Agent 之间的合并冲突
terminal
$ claude
> 让两个 agent 同时改进 src/api/index.js——一个添加错误处理，
一个添加日志。
Claude: 正在并行启动两个 agent...
[error-handler] Read: src/api/index.js
[logger] Read: src/api/index.js
[error-handler] Edit: src/api/index.js (添加 try-catch 包装)
[logger] Edit: src/api/index.js (添加请求日志中间件)
Error: src/api/index.js 中的合并冲突
[error-handler] 写入了:
app.use((err, req, res, next) => {
console.error(err.stack);
res.status(500).json({ error: 'Internal server error' });
});
[logger] 写入了:
app.use((req, res, next) => {
console.log(`${req.method} ${req.path}`);
next();
});
两个 agent 修改了文件的同一区域。
Lead 会话正在解决冲突...发生了什么：两个 Agent 同时编辑了同一个文件。当第二个 Agent 试图写入时，文件已被第一个 Agent 修改，导致冲突。
修复方法：不要分配两个 Agent 修改同一个文件。相反，构造你的任务使每个 Agent 拥有不同的文件：
Agent A: 创建 src/middleware/errorHandler.js（新文件，无冲突）
Agent B: 创建 src/middleware/logger.js（新文件，无冲突）
Lead: 两个 agent 都完成后，将两者连接到 src/api/index.js如果 Agent 必须修改同一个文件，让它们按顺序执行，而不是并行。依赖系统可以处理这种情况：将第二个 Agent 设为依赖第一个。
团队编排中的上下文溢出
terminal
$ claude
> 启动 8 个 agent 审查 monorepo 中的每个模块，然后将所有发现
综合为一份报告。
Claude: 正在并行启动 8 个审查 agent...
[agent-1] 完成。报告：2,400 tokens。
[agent-2] 完成。报告：1,800 tokens。
[agent-3] 完成。报告：3,100 tokens。
[agent-4] 完成。报告：2,200 tokens。
[agent-5] 完成。报告：2,600 tokens。
[agent-6] 完成。报告：1,900 tokens。
[agent-7] 完成。报告：2,800 tokens。
[agent-8] 完成。报告：2,500 tokens。
正在将结果收集到 lead 会话...
报告总内容：约 19,300 tokens
综合前 lead 会话上下文：145,000 / 200,000 tokens
警告：收集 8 份报告后 lead 会话已达 82% 上下文容量。
综合质量可能下降（Context Rot 阈值：50%）。
综合报告遗漏了 agent 6-8 的发现，产生了泛泛的建议
而非具体的 file:line 引用。发生了什么：每个 Agent 返回了详细的报告。将全部 8 份报告收集到 Lead 会话中，使上下文使用超过了 50% 的质量阈值。由于 Lead 会话过载，综合结果很肤浅。
修复方法：使用分层综合（Hierarchical Synthesis）。不要让一个 Lead 收集所有报告，而是将 Agent 分组并使用中间汇总器：
第一波：8 个审查 agent（并行）
第二波：2 个汇总 agent（每个处理 4 份报告，产出 500 token 的摘要）
第三波：Lead 收集 2 份摘要（总共约 1,000 tokens）或者，要求每个 Agent 产出更短的报告（不超过 500 tokens），只包含 P0 和 P1 发现。每个 Agent 一份聚焦的 500 token 报告，即使有 8 个 Agent，Lead 会话也能保持在 50% 上下文以下：
markdown
## 输出规则
- 每份报告最多 500 tokens
- 只包含 P0 和 P1 发现
- 每个发现一行：[严重级别] file:line — 描述高级：基于 tmux 的编排
ECC 的 dmux-workflows 使用 tmux 给每个 Agent 一个可见面板。在 macOS 上：
bash
# 安装 tmux
brew install tmux
# 启动 tmux 会话
tmux new -s agents
# 分割为面板并运行 agent
tmux split-window -h
tmux split-window -v
tmux select-pane -t 0 && tmux split-window -v
# 现在你有 4 个面板——一个 lead + 三个 agent
# 每个面板运行自己的 `claude` 进程在 Windows 上，使用 Windows Terminal 标签或 WSL2 配合 tmux。
练习：构建 Bug 调查团队
Bug 报告："用不同账号登录后，用户可以看到其他用户的书签。"
创建三个调查 Agent：
- log-analyst：搜索代码中的认证和会话处理。追踪用户身份如何在请求间流转。
- code-tracer：从 GET /api/bookmarks 端点开始追踪每个函数调用。映射数据流。
- exploit-writer：基于前两个的发现，写一个重现 Bug 的测试。
并行运行 log-analyst 和 code-tracer。两者完成后启动 exploit-writer。产出根因分析报告。
成功标准
- [ ] 三个 Agent 文件在
.claude/agents/中 - [ ] log-analyst 和 code-tracer 并行运行
- [ ] exploit-writer 依赖前两个完成
- [ ] 最终报告用具体 file:line 引用识别根因
- [ ] 漏洞利用测试能实际演示漏洞
知识检查
为什么 GSD 推荐全新的 200K 上下文（Wave Execution）而不是一个长时间运行的会话？
全新上下文更便宜，因为使用更少的 API token
全新上下文产出更好的结果，因为超过 50% 上下文使用后质量会下降
长时间运行的会话不被 Claude API 支持
全新上下文允许每个 wave 使用不同的模型
在 Demo 25 中，前端和后端 Agent 从未直接通信。它们是如何构建兼容代码的？
Lead 会话在两者之间实时转发消息
它们都从 CLAUDE.md 读取 API 契约，按相同的规格构建
前端等待后端完成，然后读取其输出
它们使用 Mailbox 系统来商定接口
两个并行 Agent 都需要修改 src/api/index.js。最安全的方法是什么？
让两个 Agent 都编辑文件，自动解决冲突
让每个 Agent 创建独立的新文件，然后在顺序步骤中将它们连接起来
锁定文件，一次只允许一个 Agent 访问
将两个 Agent 的上下文合并为一个，让它们共享文件状态
你启动了 8 个审查 Agent 并将所有报告收集到 Lead 会话中。综合结果肤浅，遗漏了后面 Agent 的发现。出了什么问题？
后面的 Agent 产出了质量更低的报告
收集过多报告后 Lead 会话达到了 Context Rot 阈值
Agent 因为读取相同文件而互相干扰
八个 Agent 超过了允许的最大并行会话数
总结
Agent 团队把 Claude Code 从单个开发者变成并行开发车间。本章的两个模式——多视角审查和并行功能开发——是 Agent 团队 ROI 最高的应用。
要点：
- GSD 的 Wave Execution：全新的 200K 上下文比被污染的长时间运行会话产出更好
- gstack 的多角色审查：产品 + 设计 + 工程捕获单一视角审查遗漏的问题
- 任务依赖：能并行就并行，需要串行就串行
- 共享契约（CLAUDE.md）比 Agent 间实时通信更可靠
- Mailbox 通信让 Agent 在需要实时数据交换时能够协调
- ECC 的 dmux-workflows 通过 tmux 提供可视化编排
- 收集大量 Agent 报告时注意上下文溢出——使用分层综合
恭喜你完成了进阶篇！
接下来挑战阶段性大项目：PR 审查机器人，综合运用 Ch5-9 的所有知识。
或者直接进入阶段三：高级篇 — Chapter 10: 权限与安全。