Claude Code 原生 Agent Teams 上手实战：从开启到跑通一个三人团队

上一篇我拆了 GitHub 上几个社区多 Agent 框架的角色设计。这篇换个方向——不用社区框架，直接用 Claude Code 内置的 Agent Teams 功能。

2 月 6 号，Anthropic 随 Opus 4.6 一起正式开放了这个功能。之前有人从二进制文件里 strings 出了 TeammateTool 的完整 schema，当时还是 feature-flagged off 的状态。现在开关打开了，官方文档也上线了。

我花了一天时间从零配到跑通，记录一下过程。

01 Agent Teams 和 Subagents 的区别

先厘清概念。Claude Code 里有两种"多 Agent"机制，很多人搞混。

Subagents：在同一个会话里派生子 Agent。子 Agent 做完任务把结果交回来，只能跟主 Agent 单向通信。适合"帮我查个东西、跑个脚本"这种一次性任务。

Agent Teams：每个 Agent 是一个独立的 Claude Code 实例，有自己的上下文窗口。Agent 之间可以互相发消息、互相挑战观点。有共享任务列表，有文件锁防冲突。适合需要多人协作、并行探索的复杂任务。

用一张表说清楚：

维度	Subagents	Agent Teams
上下文	共享主 Agent 的上下文窗口	每个 Agent 独立上下文
通信方式	单向：子 → 主	双向：任意 Agent 之间
协调机制	主 Agent 统一管理	共享任务列表 + 自协调
适合场景	聚焦型任务，只需要结果	需要讨论、挑战、协作的复杂任务
Token 开销	较低（结果摘要回传）	较高（每个 Agent 独立实例）

核心区别：Subagents 是"我给你派个活，你干完汇报"。Agent Teams 是"你们三个人组个队，自己商量着干"。

02 开启 Agent Teams

Agent Teams 目前是实验性功能，默认关闭。两种开启方式。

方式一：环境变量

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

加到 .zshrc 或 .bashrc 里，重启终端生效。

方式二：settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

推荐用 settings.json，不污染全局环境变量。

开启之后不会有明显的 UI 变化。只有当你在对话里明确要求 Claude 创建团队时，它才会启动 Agent Teams 功能。

03 跑通第一个三人团队

我拿了一个实际场景测试：让 Agent Teams 对一个 PR 做并行 Code Review。

启动团队

在 Claude Code 里输入：

Create an agent team to review the changes in src/auth/. 
Spawn three reviewers:
- One focused on security implications
- One checking performance impact  
- One validating test coverage
Have them each review and report findings.

Claude 收到之后会做三件事：

1. 创建一个 Team，自己作为 Team Lead
2. 派生三个 Teammate，每个有独立的上下文窗口
3. 给每个 Teammate 分配任务，写入共享任务列表

显示模式

Agent Teams 支持两种显示模式：

In-process 模式（默认）：所有 Teammate 在同一个终端里运行。用 Shift+Up/Down 切换查看不同 Teammate 的输出，直接打字就能给选中的 Teammate 发消息。

Split-pane 模式：每个 Teammate 一个独立面板，需要 tmux 或 iTerm2。

{
  "teammateMode": "tmux"
}

如果你用 macOS + iTerm2，推荐 tmux -CC 进入 split-pane 模式，视觉效果最好——三个面板同时刷输出，像在看三个开发者同时干活。

单次会话临时切换：

claude --teammate-mode in-process

观察团队协作

启动后，三个 Reviewer 开始并行工作。在我的测试里：

• Security Reviewer 花了约 2 分钟，扫描了 token 处理、session 管理、输入验证
• Performance Reviewer 花了约 1 分 40 秒，关注 N+1 查询、内存分配、缓存命中率
• Test Coverage Reviewer 花了约 1 分 50 秒，检查边界条件覆盖、mock 是否合理

三个人跑完后，Lead 自动汇总了发现。总耗时约 3 分钟（并行），如果用单 Agent 串行做同样的事大概要 6-7 分钟。

有意思的是 Lead 的汇总不是简单拼接三份报告。它会做交叉验证——比如 Security Reviewer 标记了一个"高危"问题，Lead 会看 Test Coverage Reviewer 的报告里有没有覆盖这个场景的测试。如果没有，它会额外标注"安全漏洞 + 测试缺失"。

04 关键操作速查

给 Teammate 发消息

In-process 模式下 Shift+Up/Down 选择 Teammate，直接打字发送。

Split-pane 模式下点击对应面板即可。

任务分配

共享任务列表有三种状态：pending → in progress → completed。

任务可以设置依赖关系：A 任务完成后 B 任务才能开始。框架自动管理依赖解锁。

Lead 可以主动分配任务，Teammate 也可以自己认领（self-claim）。用文件锁防止两个 Teammate 同时认领同一个任务。

Delegate 模式

默认情况下 Lead 有时会忍不住自己干活，而不是分给 Teammate。如果你想让 Lead 纯粹做协调，按 Shift+Tab 进入 Delegate 模式。

Delegate 模式下 Lead 只能做四件事：派生 Teammate、发消息、关闭 Teammate、管理任务。不能自己写代码。

这个设计很实用。你不希望项目经理自己下场写代码，尤其是当他写的代码可能和 Teammate 的产出冲突的时候。

Plan Approval

对高风险任务，可以要求 Teammate 先出方案再动手：

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

Teammate 会在 read-only 的 plan mode 下工作，写好方案后提交给 Lead 审批。Lead 通过才能进入实现阶段。

你可以在 prompt 里给 Lead 设审批标准："只批准包含测试覆盖的方案"、"拒绝修改数据库 schema 的方案"。Lead 会按你的标准自主决策。

质量门禁（Hooks）

通过 Hooks 系统在关键节点插入自动检查：

• TeammateIdle：Teammate 要空闲时触发。脚本返回 exit code 2 会把 Teammate 踢回去继续干。
• TaskCompleted：任务标记完成时触发。脚本返回 exit code 2 会阻止任务完成并附带反馈。

比如你可以写一个 Hook：每当 Teammate 标记"写完代码"的任务为 completed 时，自动跑一遍 lint 和单元测试。测试不过就打回去。

05 成本估算

Agent Teams 的 Token 消耗显著高于单 Agent。每个 Teammate 是一个独立的 Claude 实例，有自己的上下文窗口。

粗略估算（基于 Opus 4.6 定价 $5/$25 每百万 token）：

场景	Agent 数量	预估 Token 消耗	预估成本
单文件 Code Review	1（单 Agent）	~15K	~$0.04
并行三人 Code Review	3 Teammates + 1 Lead	~55K	~$0.15
多模块并行重构	4 Teammates + 1 Lead	~120K	~$0.35
竞争假设 Debug	5 Teammates + 1 Lead	~150K	~$0.45

三人 Code Review 的成本约为单 Agent 的 4 倍，但时间省了一半，而且多视角交叉检查能发现单 Agent 漏掉的问题。

是否值得？取决于你的场景。如果是生产环境的安全审计，多花 $0.11 换来更全面的审查，值。如果是自己练手项目的日常 commit，单 Agent 够用。

06 踩坑记录

用了一天，记几个坑。

坑一：Lead 抢活干

默认情况下 Lead 经常自己动手写代码，而不是等 Teammate 干完。解决方法是开 Delegate 模式，或者在对话里明确说："Wait for your teammates to complete their tasks before proceeding."

坑二：Teammate 不标记任务完成

偶尔 Teammate 干完了活但忘记把任务状态改成 completed，导致依赖它的下游任务一直 pending。需要手动提醒 Lead 去催对应的 Teammate 更新状态。

坑三：session 恢复不了

用 /resume 或 /rewind 恢复会话时，in-process 模式的 Teammate 不会跟着恢复。Lead 可能会尝试给已经不存在的 Teammate 发消息。碰到这种情况，让 Lead 重新 spawn 新的 Teammate。

坑四：文件冲突

两个 Teammate 编辑同一个文件会互相覆盖。这是最容易踩的坑。启动团队的时候就要规划好每个 Teammate 负责的文件范围，确保不重叠。

坑五：tmux 残留

如果团队没正常 cleanup 就退出了，tmux session 会残留。手动清理：

tmux ls
tmux kill-session -t <session-name>

正常流程是先让 Lead shutdown 所有 Teammate，再让 Lead cleanup 团队。

07 什么时候该用 Agent Teams

用了一天下来，我的判断标准：

适合用 Agent Teams 的场景：

• 多角度 Code Review（安全 + 性能 + 测试覆盖）
• 竞争假设 Debug（多个 Agent 同时验证不同猜测，互相挑战）
• 新模块并行开发（前端、后端、测试各一个 Teammate）
• 跨层协调变更（改一个功能涉及 API、数据库、前端三层）

不适合用 Agent Teams 的场景：

• 串行任务（A 做完 B 才能做）
• 同一个文件的密集编辑
• 简单查询或一次性脚本
• 依赖关系复杂到需要精细调度的任务

一句话总结：如果任务能拆成互不干扰的独立块并行跑，用 Agent Teams；如果任务本质上是线性的，单 Agent 或 Subagents 更划算。

08 和社区框架的关系

上篇文章里我拆了 bradms98/claude-agent-team、claude-colony、cc-dev-team 等社区项目。现在官方出了原生 Agent Teams，这些社区框架还有意义吗？

有，但定位变了。

官方 Agent Teams 解决了底层编排问题：团队创建、消息通信、任务管理、生命周期控制。社区框架之前在做的很多脏活累活（tmux 编排、文件消息传递、进程管理），现在官方都接管了。

但社区框架在"角色预设"上的积累仍然有价值。比如 cc-dev-team 的 44 个专业 Agent 角色定义、每个角色的 system prompt，这些是官方 Agent Teams 没有提供的。官方给你的是"能组队"，但"队伍怎么配"还是你自己定。

我的做法是用官方 Agent Teams 做底层编排，参考社区框架的角色设计来写 spawn prompt。两者不是替代关系，是互补。

---

Agent Teams 目前还是实验阶段，限制不少（不能嵌套团队、不能换 Lead、session 不能恢复）。但核心工作流已经跑通了。如果你在用 Claude Code 做多模块项目，值得花半小时试一下。