主题
3.9 Agent Teams — 组建 AI 团队并行干活
学习目标
学完这节课，你将能够：
- 区分 Agent Teams 和子智能体（Sub-agents）的本质差异
- 在 settings.json 中正确开启 Teams 功能
- 设计灵活的团队角色，摆脱传统软件工程的固定角色思维
- 掌握"调研、审核、测试"三角色通用模板并直接上手使用
- 理解 Teams 的限制和适用场景
先搞清楚：Teams 不是子智能体
3.1 节讲过子智能体——主 Claude Code 派出分身去执行子任务，分身干完活把结果交回来，整个过程在一个 Claude Code 实例内部完成。
Agent Teams 完全不是这个东西。
Teams 是多个独立的 Claude Code 实例在同一个项目里并行协作。每个实例叫一个 teammate，它们各自有独立的终端、独立的上下文窗口、独立的对话历史，但可以通过协议互相通信、分配任务、传递结果。
子智能体模式：
你 → Claude Code 实例
├── 子智能体 A（分身，内部线程）
├── 子智能体 B（分身，内部线程）
└── 子智能体 C（分身，内部线程）
Agent Teams 模式：
你 → Claude Code 实例 1（Leader）
├── Claude Code 实例 2（Teammate：调研）
├── Claude Code 实例 3（Teammate：编码）
└── Claude Code 实例 4（Teammate：审核）
每个都是独立进程，各自占一个终端窗口打个比方：子智能体像是一个人同时开了三个脑内线程，而 Agent Teams 像是真的叫来了三个同事坐在旁边一起干活。
最直观的区别：子智能体共享 Leader 的上下文限制，处理大项目时容易撞到上下文天花板。而 Teams 的每个 teammate 都有自己完整的上下文窗口，处理大规模任务时从容得多。
前置条件：开启 Teams 功能
Agent Teams 目前是实验性功能，默认关闭。你需要在 settings.json 里手动开启。
打开你的全局配置文件 ~/.claude/settings.json，在 env 字段里加一行：
json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}如果你跟着前面的课程走过来，这个配置应该已经在那了（0.7 节的全局配置里提到过）。
[截图: settings.json 中 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 设置为 "1" 的位置]
保存文件后，重启 Claude Code 即可生效。不需要装额外的插件，不需要改其他配置，就这一行。
团队角色设计 — 忘掉你的传统思维
这是整节课最重要的观念转变。
传统软件团队的角色是固定的：项目经理就是项目经理，测试工程师就是测试工程师，前端就是前端。一个人入职后角色基本不变，可能干三年都是同一个定位。
Agent Teams 不需要这样想。
每个 teammate 的角色是按任务定制的。同一个任务里，你可以给 teammate 设定非常具体的专长方向；换一个任务，完全可以重新定义角色。没有什么"固定编制"的说法。
举几个例子感受一下：
场景 1：做一个电商首页
| Teammate | 这次的角色 |
|---|---|
| A | 调研当前最流行的电商 UI 设计趋势和组件库 |
| B | 基于调研结果实现页面 |
| C | 审核代码质量和响应式适配 |
场景 2：优化 API 性能
| Teammate | 这次的角色 |
|---|---|
| A | 调研业内主流的 API 缓存方案和性能优化策略 |
| B | 实现优化方案 |
| C | 用压力测试工具验证优化效果 |
场景 3：做安全审计
| Teammate | 这次的角色 |
|---|---|
| A | 专注 OWASP Top 10 漏洞扫描 |
| B | 专注依赖包的 CVE 漏洞检查 |
| C | 汇总两边结果，输出修复方案 |
看到了吗？同样是三个 teammate，三个场景下角色完全不同。甚至你可以更细——给某个 teammate 指定"你精通 Tailwind CSS 和 Radix UI，不要用其他方案"。这种级别的定制在传统团队里是不可能的，但在 Agent Teams 里只需要一句话。
核心理念：别想着"我有几个固定工种"，想着"这个任务需要什么样的专家组合"。
三个必备角色 — 通用模板
虽然角色应该按任务定制，但有三个角色几乎在所有场景下都用得到。把它们当作起手式，然后根据具体任务再调整。
1. 调研 Teammate
为什么必须有它： 技术选型选错一步，后面全是返工。选了一个半年没更新的库、用了一个社区已经在弃用的方案、或者不知道隔壁竞品已经有了更好的实现——这些坑，一个调研 teammate 就能帮你避开。
它干什么： 在任何技术决策落地之前，先去搜索当前最好的方案。技术选型、架构设计、组件库选择、甚至只是要挑一个图标库，都让它先跑一圈。
举个真实场景： 你要给项目加一个 Markdown 编辑器。直接开写？等一下——先让调研 teammate 去搜：现在最流行的 Markdown 编辑器组件有哪些？stars 最多的是哪个？哪个对 Next.js 的 SSR 支持最好？哪个有现成的 AI 辅助写作插件？五分钟后它给你一份对比表，你选一个最合适的再动手。
比你自己花半小时搜 Google，然后在三个库之间纠结，最后选了一个才发现它不支持你的框架——这个体验好太多了。
2. 审核 Teammate
为什么必须有它： AI 写的代码并不总是对的。让写代码的 AI 自己审查自己的代码，就像让学生自己批改自己的考卷——总会有盲区。
它干什么： 专门对别的 teammate 完成的代码进行审核。不通过？打回去重写。重写完了？继续审。这个循环一直转，直到代码质量过关。
审核维度：
- 逻辑是否正确，有没有漏掉边界情况
- 命名和风格是否和项目现有代码一致
- 有没有性能隐患或安全风险
- 是否遵循了项目的设计规范（如果有的话）
这个角色最关键的一点：它和写代码的 teammate 是完全独立的上下文。它不知道写代码时的思考过程，只看到最终的代码输出——这恰恰是好的代码审查应该有的状态。
3. 测试 Teammate
为什么必须有它： 审核 teammate 看的是代码质量，但代码"看着没问题"和"跑起来没问题"是两回事。
它干什么： 对审核通过的代码编写测试用例并执行。单元测试、集成测试，根据场景决定。测试不通过，把失败信息反馈给审核 teammate，由审核 teammate 决定是打回去重写还是自己调整。
流程串起来：
调研 teammate → 输出技术方案
↓
编码 teammate 基于方案实现
↓
审核 teammate 审查代码 ← 不通过？打回重写
↓ 通过
测试 teammate 编写并运行测试 ← 不通过？反馈给审核
↓ 通过
最终交付这三个角色形成了一条完整的质量链：调研保证方向不跑偏，审核保证代码质量，测试保证功能可用。
直接能用的提示词模板
不想自己从零设计？直接复制下面这段提示词，把最后的"任务"部分换成你的具体需求就行：
帮我构建teams（不是子代理）（1.参考claudecode agent-teams的官方文档的用法 2.角色设计不要用传统软件工程思路）spawn 多个 teammates 并行干活，必须包含以下teammates：
1.调研teammates：决定某个架构或者方案前先调研，去网上搜索对比当前最好的实现方案、最流行的技术栈、最适合当前项目的选型。输出对比分析报告后再让其他teammates动手。
2.审核teammates：专门负责对别的teammates完成的代码进行审核，审核不通过打回去重写，重写完继续审核，反复循环直到通过。审核维度包括逻辑正确性、边界情况、代码风格一致性、安全风险。
3.测试teammates：对审核teammates通过的功能代码进行测试，编写并运行单元测试和集成测试。测试不通过的反馈给审核teammates，由审核teammates打回给编码teammates重写。
任务如下：
（在这里写你的具体任务）[截图: 把上面的提示词粘贴到 Claude Code 中，Claude 开始 spawn 多个 teammates 的过程]
使用建议：
- 如果任务比较简单（比如改一个按钮样式），不需要这么大阵仗，直接跟 Claude Code 说就行
- 如果任务涉及技术选型、多文件改动、或者你对结果质量要求很高，上 Teams
- 可以根据具体任务加减角色，比如纯前端任务可以加一个"UI 走查 teammate"，数据库任务可以加一个"性能基准测试 teammate"
实战演示：用 Teams 构建一个用户反馈模块
来看一个完整的例子，感受 Teams 的协作过程。
任务： 给项目添加一个用户反馈收集功能，包含前端表单和后端 API。
第一步：发出指令
把上面的模板复制过来，填入具体任务：
帮我构建teams（不是子代理）spawn 多个 teammates 并行干活，必须包含以下teammates：
1.调研teammates：调研当前最好的用户反馈组件实现方案
2.审核teammates：审核代码质量
3.测试teammates：编写并运行测试
任务如下：
给项目添加一个用户反馈收集功能。前端需要一个反馈表单（支持文字+截图），
后端需要一个 API 接收并存储反馈数据。第二步：Teams 开始工作
Claude Code 收到指令后，会 spawn 出多个 teammates。你能看到每个 teammate 在独立工作：
[Leader] 正在分配任务...
[Teammate: 调研] 正在搜索用户反馈组件的实现方案...
→ 对比了 react-feedback-widget、feedbackfish、自建方案
→ 推荐：自建方案 + react-dropzone 处理截图上传
→ 输出：技术选型报告
[Teammate: 编码] 基于调研结果开始实现...
→ 创建 FeedbackForm 组件
→ 创建 /api/feedback 端点
→ 创建数据库 schema
[Teammate: 审核] 审查编码 teammate 的产出...
→ 发现问题：截图上传缺少文件大小限制
→ 发现问题：API 端点缺少 rate limiting
→ 打回重写
[Teammate: 编码] 根据审核意见修改...
→ 添加 5MB 文件大小限制
→ 添加 rate limiting 中间件
[Teammate: 审核] 二次审查...
→ 通过
[Teammate: 测试] 编写并运行测试...
→ 单元测试：表单验证逻辑 ✓
→ 集成测试：API 端点 ✓
→ 边界测试：超大文件上传拒绝 ✓
→ 全部通过[截图: 终端中多个 teammates 同时工作的实际输出，能看到不同 teammate 的标识和进度]
第三步：查看结果
所有 teammates 完成后，Leader 汇总结果。你得到的不只是代码，还有：
- 调研 teammate 的技术选型报告
- 审核 teammate 的审查记录（包括打回了什么、为什么打回）
- 测试 teammate 的测试覆盖报告
[截图: Leader 汇总所有 teammates 的工作成果，给出最终交付报告]
限制和注意事项
Teams 很强大，但不是万能的，有几点你需要知道：
1. 实验性功能
目前 Agent Teams 还在实验阶段（需要手动开启环境变量就说明了这一点）。Anthropic 可能会在后续版本中调整 API 和行为。日常使用没问题，但别在生产环境的 CI/CD 里硬依赖它。
2. 资源消耗
每个 teammate 都是一个独立的 Claude Code 实例，意味着：
- 每个 teammate 都会消耗 API token
- 三个 teammate 并行 = 大约三倍的 token 用量
- 如果你的 API 有速率限制，多个 teammate 同时请求可能会触发限流
建议： 简单任务不要上 Teams。杀鸡别用牛刀。
3. 文件冲突
多个 teammates 如果同时修改同一个文件，可能会产生冲突。好的做法是：
- 在任务分配时明确每个 teammate 负责的文件范围
- 让 Leader 协调好先后顺序
- 如果用了 Git Worktree（3.4 节），每个 teammate 在自己的 worktree 里工作，天然隔离
4. 上下文隔离
每个 teammate 的上下文是独立的。这是优点（不互相污染），但也意味着如果 teammate A 的产出需要 teammate B 理解，Leader 需要把相关信息传递过去。复杂任务中，这个"信息传递"的质量直接决定了最终结果。
5. 与子智能体的选择
什么时候用子智能体，什么时候用 Teams？
| 维度 | 子智能体 | Agent Teams |
|---|---|---|
| 任务规模 | 小到中等 | 中等到大型 |
| 上下文需求 | 共享主上下文 | 各自独立上下文 |
| 资源消耗 | 较低（同一实例内） | 较高（多个实例） |
| 通信成本 | 低（内部线程） | 较高（跨实例协议） |
| 适合场景 | 快速的代码审查、文件探索 | 多文件重构、全栈功能开发 |
一个简单的判断标准：如果你觉得一个人忙得过来（只是需要换换脑子），用子智能体；如果你觉得真的需要"加人"，用 Teams。
小结
- Agent Teams 不等于子智能体：Teams 是多个独立 Claude Code 实例并行协作，子智能体是单实例内的分身
- 开启方式：
settings.json中设置CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" - 角色设计要灵活：忘掉固定工种，针对每个任务定制最合适的专家组合
- 三角色通用模板：调研（保证方向对）→ 审核（保证质量高）→ 测试（保证能跑通），覆盖绝大部分场景
- 直接复制提示词模板，改掉任务描述就能用
- 注意资源消耗和文件冲突，简单任务不要过度使用 Teams
实用建议：第一次用 Teams 不要上来就搞大项目。先拿一个小功能试试手，感受一下 teammates 之间的协作节奏，踩过一遍坑之后再用到正式开发中。跟带新人一样，先让团队磨合磨合。