Claude Code Agent Teams 实战：多代理并行协作的边界与方法

如果你的任务需要多个 Claude 实例并行协作，Agent Teams 是官方提供的系统化方案。它不是简单的多开会话，而是带有负责人、队友、共享任务列表与邮箱通信机制的协作系统。

推荐使用场景：

1. 多方向研究或代码审查，需要不同角色并行产出结论。
2. 竞争假设调试，需要代理互相质疑而不是单线探索。
3. 跨前后端与测试的并行推进，且各子任务可相对独立。

不推荐使用场景：

1. 串行依赖强的任务。
2. 多人频繁编辑同一文件的任务。
3. 日常低复杂度改动。

核心判断标准很直接：如果并行探索的收益大于协调和 token 成本，就用 Agent Teams。否则优先单会话或 Subagents。

两者都能并行，但设计目标不同：

1. Subagents：轻量委派，结果回主代理，成本更低。
2. Agent Teams：独立会话协作，队友可直接通信，成本更高。

实践上可以这样选：

1. 只需要“有人去查，然后回来汇报”时，用 Subagents。
2. 需要“多人讨论、互证、自协调”时，用 Agent Teams。

Agent Teams 当前是实验能力，需要先开启环境变量：

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

启动时直接给负责人自然语言目标和角色分工即可。建议初始团队规模控制在 3-5 人，这也是官方文档中最稳妥的经验区间。

团队结构包含四个核心组件：

1. Team lead：创建团队、分配任务、综合结果。
2. Teammates：独立 Claude 实例，各自运行在独立 context 中。
3. Task list：共享任务池，支持依赖关系与状态流转。
4. Mailbox：代理间消息系统，支持定向 message 与 broadcast。

这套机制使团队具备“自协调”能力，而不是所有沟通都绕回主会话。

支持两种模式：

1. in-process：全部在主终端内，轻量、兼容性好。
2. split panes：每个队友一个窗格，需要 tmux 或 iTerm2 + it2 CLI。

推荐默认使用 in-process 起步，确认协作模型有效后再切换分屏可视化。

Agent Teams 的 token 成本会随活跃队友线性上升，这是必须明确接受的 trade-off。为了避免“贵且乱”，建议强制以下规则：

1. 任务拆分按文件边界切，避免文件冲突。
2. 单任务颗粒度保持可交付（函数、测试、评审结论），不要过大。
3. 每个队友挂 5-6 个任务上限，降低频繁上下文切换。
4. 使用 hooks 作为质量门：TeammateIdle 和 TaskCompleted 失败即阻断。

1. 先从研究/评审类任务开始试点，不直接并行编码。
2. 负责人先定义任务列表与依赖关系，再发起分配。
3. 每轮结束做一次汇总，及时关闭无效路径。
4. 完成后先优雅关闭队友，再执行团队清理。

1. 队友未出现：先检查任务复杂度是否足以触发团队，确认 tmux/it2 环境。
2. 权限弹窗过多：预先在权限配置中放行高频安全操作。
3. 队友出错后停滞：直接切到该队友补充指令或生成替代队友接手。
4. 任务卡住：核对依赖是否已满足，必要时手动修正任务状态。

当前版本需重点关注几个限制：

1. in-process 队友不支持完整会话恢复链路。
2. 一个会话同一时刻只能带一个团队。
3. 不支持嵌套团队。
4. 队友权限在生成时继承负责人模式。

这意味着 Agent Teams 更适合作为“高价值并行场景”的专项武器，而不是默认工作模式。

Agent Teams 的价值不在“同时开更多 Claude”，而在“把并行协作做成有结构的系统工程”。

当任务可独立拆分、边界清晰、质量门明确时，它会显著缩短收敛时间；当任务强耦合或边界模糊时，协调成本会迅速吞掉收益。

因此，真正的最佳实践是：先判断并行价值，再上团队机制。