今天我们要探索一个更进阶的（也是新鲜出炉的）协作模式：Agent Teams（智能体团队）。

注意：Agent Teams 是 Claude Code 的实验性功能，默认关闭。需要在相关级别的设置文件中（如用户级设置 ~/.claude/settings.json 或 项目级设置 project_folder/.claude/settings.json）添加 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量来启用。Claud Code 官方说，这个实验性功能可能存在已知限制（具体限制可以参考官网实时更新的说明，搜索“limitations”关键字），生产环境请谨慎评估。

Sub-Agents vs Agent Teams：从“任务委托”到“团队协作”

前面几篇文章介绍的子代理工作模式虽然也各有差异，但是基本模式一致。都是主对话像老板一样，把任务委派给各个专职员工（子代理）。这种模式解决了上下文污染、权限边界、任务并行等问题。但它有一个根本性的限制：子代理只能向主对话汇报，不能互相交流。

Claude_Code_sub_agents_single_proxy

这在很多场景下足够好用。但我们在实际生产环境中可能会遇到更复杂、更诡异的场景：比如多假设并行验证。

你的系统出现了一个奇怪 bug——用户登录后偶尔会话丢失，没有明确的规律。你怀疑可能是：

  • 假设 A：JWT token 过期时间计算有问题
  • 假设 B：Redis session 存储的竞态条件
  • 假设 C：负载均衡器的 sticky session 配置

如果用子代理，情况可能是这样：

Claude_Code_agent_teams

如果子代理 B 能看到子代理 C 的发现，它可能会说：等等，Redis 连接数上限问题可能是因为 sticky session 5 分钟后切换了服务器，导致新的 Redis 连接被创建。

这正是 Agent Teams 要解决的问题——让代理之间能够直接交流、互相挑战、协作推进。

Agent Teams 让你可以协调多个 Claude Code 实例作为一个团队工作。一个会话作为 Team Lead（团队领导），协调工作、分配任务、综合结果。Teammates（队友）各自独立工作，每个都有自己的上下文窗口，并且可以直接互相通信。

Claude_Code_agent_teams

因此我们说，“Agent Teams 模式”与“主会话 - 子代理模式”最本质的区别是，Teammates 可以互相发消息、共享发现、挑战彼此的结论。

创建和使用 Agent Teams

Agent Teams 默认是关闭的，启用方式是在 settings.json 中设置环境变量：

1
2
3
4
5
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

或者在 shell 环境中设置：

1
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

在 Claude Code 中可以通过下面两种方式创建团队：
Claude_Code_agent_teams

两种方式你都保持控制权——Claude 不会未经你批准就创建 team。

启用后，用自然语言告诉 Claude 创建团队并描述任务：

1
2
3
我在设计一个 CLI 工具来追踪代码库中的 TODO 注释。
创建一个 agent team 从不同角度探索这个问题：
一个 teammate 负责 UX，一个负责技术架构（用最好的模型），一个扮演审评质疑者（用普通模型）。

Claude 会建团队，生成指定的 Teammates 让它们探索问题，然后综合各方发现，完成后清理团队。

实战项目：全栈 Bug 猎人

项目场景是一个 Express.js 电商应用（ShopStream），其中刻意植入了多个相互关联 bug。用户报告了三个看似独立的症状：会话丢失、API 变慢、数据泄漏。真相是这些症状由相互 bug 的级联故障造成：

1
2
3
4
5
6
7
8
9
Bug 1: DB 连接池太小（db.js）
    ↓ 连接耗尽
Bug 2: Redis Session 不处理重连（middleware/session.js）
    ↓ Session 写入静默失败
Bug 3: 订单查询 N+1 问题（routes/orders.js）
    ↓ 大量连接被占用 → 加剧 Bug 1
Bug 4: 缓存竞态条件（middleware/cache.js）
    ↓ 缓存 key 缺少用户标识 → 数据泄漏
    ... ...

那么为什么这里需要 Agent Teams 呢？

因为单独调查者容易“锚定”，找到一个 bug 后就满意了，不继续挖掘。而 bug 之间的关联需要跨视角发现，只有 Session 侦探和数据库侦探各自的发现互相对照，才能看到级联效应。此外，架构侦探可以把其他侦探的发现串联起来，通过辩论机制产出更完整的根因链。

四大协作设计模式

Agent Teams 最强大的地方在于它支持的协作模式。

模式一：竞争假设（Competing Hypothesis）

这种模式适用于根因不明确，需要从多个方向同时验证的场景。

单个 Agent 调查时容易“锚定”——找到一个合理解释后就停止探索，可能错过真正的根因。此时，让多个 Teammates 各自持有不同假设，并要求它们互相挑战、试图推翻对方的理论。

1
2
3
4
用户报告应用在发送一条消息后就退出了，而不是保持连接。
生成 5 个 agent teammates 调查不同的假设。
让它们互相对话，试图推翻对方的理论，像科学辩论一样。
将最终共识更新到 findings 文档。

该模式架构如下：
Claude_Code_agent_teams_competing_hypothesis

想一想，这种模式的工程价值在哪里？

  • 避免锚定效应——多个独立调查者，各自寻找证据支持自己的假设。
  • 辩论机制迫使每个假设必须经受挑战才能“存活”。
  • 最终“存活”的假设更可能是真正的根因。

为什么辩论结构是此处的关键机制？顺序调查会收到锚定偏见的影响，一旦第一个理论被探索，后续调查会不自觉地偏向它。多个独立调查者主动互相反驳，幸存下来的理论更可能是真正的根因。

模式二：分层评审（Parallel Review）

这种模式适用于代码审查、PR Review 等需要从多个维度同时评估的任务。

因为单个 reviewer 容易聚焦于某一类问题（比如只看代码风格），而忽略其他维度。让多个 Teammates 各自负责不同的审查维度，同时工作。

1
2
3
4
5
创建一个 agent team 来审查 PR #142。生成三个 reviewer：
- 一个专注安全隐患
- 一个检查性能影响
- 一个验证测试覆盖
让它们各自审查并汇报发现。

该模式架构如下：
Claude_Code_agent_teams_parallel_review

这种模式的工程价值有哪些呢？

  • 每个维度都得到充分关注，不会因为注意力分散而遗漏。
  • 并行执行，时间成本不增加。
  • 不同专家可能发现关联问题（Security Reviewer 发现的输入验证问题可能影响 Performance）

模式三：模块化开发（Module Ownership）

这种模式适用于新功能开发，涉及多个独立模块（前端、后端、数据库、测试）的场景。

由于让一个 Agent 依次开发容易混淆上下文，多个子代理并行又无法协调接口。因此，让每个 Teammate 拥有一个模块，通过共享任务列表协调工作。

该模式架构如下：
Claude_Code_agent_teams_module_ownership

这种模式的关键机制是：

  • 任务依赖：任务可以声明依赖其他任务，被阻塞的任务不能被认领。
  • 自动解锁：当依赖任务完成后，被阻塞的任务自动变为可认领。
  • 文件所有权：每个 Teammate 负责不同的文件，避免冲突。

模式四：规划 - 审批（Plan Approval）

这种模式适用于复杂或高风险任务，需要在实施前确认方案。

如果直接让 Teammate 开干，可能因方向错误导致返工。因此要求 Teammate 在实施前先提交计划，Lead 审批通过后才能执行。

1
2
生成一个 architect teammate 来重构认证模块。
要求在修改任何代码前先提交计划等待审批。

该模式工作流如下：

Claude_Code_agent_teams_plan_approval

控制 Lead 的审批标准：

1
2
3
4
生成一个 architect teammate 来重构认证模块。
要求在修改任何代码前先提交计划等待审批。
只批准包含测试计划的方案。
拒绝任何修改数据库 schema 的方案。

Lead 会根据你提供的标准自主做出批准 / 拒绝决策。你影响 Lead 判断的方式是在 prompt 中给出明确的标准，比如“只批准包含测试覆盖的方案”或“拒绝修改数据库 schema 的方案”。

Sub-Agents vs Agent Teams：选型决策树

到底 Sub-Agents 和 Agent Teams 这两种架构如何选择？这里给出一个选型决策树：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
你的任务需要多个 workers 吗？
├── 否 → 直接在主对话或用单个子代理
└── 是 → Workers 需要互相通信吗？
    ├── 否 → Sub-Agents
    │   └── 特点：
    │       • 更低 token 成本
    │       • 更简单的协调
    │       • 适合：并行探索、流水线编排
    │
    └── 是 → Agent Teams
        └── 特点：
            • 支持讨论和挑战
            • 共享任务列表
            • 适合：竞争假设、协作开发、多角度审查

一句话总结，核心判断标准是你的 workers 是否需要互相通信？Sub-Agents 是快速、廉价的“派出去 - 带回来”模式，如果只需汇报结果 ，就选 Sub-Agents；Agent Teams 是复杂、协作的“组队讨论”模式，如果需要互相讨论、挑战、协调 ，就选 Agent Teams。

token成本考量

Claude 指出，Agent Teams 使用的 token 显著高于单会话或子代理，因为每个 Teammate 是独立的 Claude 实例，有独立的上下文窗口。消息通信消耗额外 token，而且团队越大，成本越高。

因此，适合 Agent Teams 的任务特征包括：

  • 并行探索能带来真正的价值；
  • 讨论和挑战能提高结果质量；
  • 任务复杂度值得额外成本。

不适合 Agent Teams 的任务特征包括：

  • 常规任务，单会话就够；
  • 任务之间没有协作需求以及预算有限的场景。