Agent Teams 让多个 Claude Code 实例作为团队协作——一个作为 Lead 协调工作，多个 Teammate 各自拥有独立上下文、可以直接互相通信。
Agent Teams 处于实验阶段，默认禁用，存在已知限制（会话恢复、任务协调、关闭行为）。
启用 Agent Teams
json
// settings.json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}或临时启用：
bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claudeAgent Teams vs Subagents：如何选择？
| 特性 | Subagents | Agent Teams |
|---|---|---|
| 上下文 | 各自独立；结果回报给调用者 | 各自完全独立 |
| 通信 | 只向主 Agent 汇报 | Teammate 之间可以直接通信 |
| 协调方式 | 主 Agent 管理所有工作 | 共享任务列表，自主认领 |
| 最适合 | 专注任务，只关心结果 | 需要讨论、协作、互相挑战的复杂工作 |
| Token 消耗 | 较低（结果摘要回主上下文） | 较高（每个 Teammate 是独立 Claude 实例） |
选择 Agent Teams 的信号：Teammate 之间需要共享发现、互相质疑、相互协调，而不仅仅是完成各自的任务后汇报。
最适合 Agent Teams 的场景
- 研究与审查：多个 Teammate 并行调查同一问题的不同方面，共享并挑战彼此发现
- 独立模块开发：每个 Teammate 负责一个模块，互不干扰
- 竞争假设调试：多个 Teammate 并行测试不同故障假设，更快收敛到答案
- 跨层协调：前端、后端、测试分别由不同 Teammate 负责
启动第一个 Agent Team
我在设计一个 CLI 工具，帮助开发者追踪代码库中的 TODO 注释。创建一个 Agent Team 从不同角度探索这个问题：一个 Teammate 负责 UX，一个负责技术架构，一个扮演唱反调的角色。
Claude 会：
- 创建带共享任务列表的团队
- 为每个视角 spawn Teammate
- 让他们探索问题
- 综合发现
- 任务完成后自动清理团队
Lead 终端列出所有 Teammate 及其正在做的事。按 Shift+Down 循环切换 Teammate，直接发消息。最后一个 Teammate 后继续按 Shift+Down 回到 Lead。
显示模式
| 模式 | 说明 | 要求 |
|---|---|---|
| In-process（默认） | 所有 Teammate 在主终端内；Shift+Down 切换 | 任意终端 |
| Split panes | 每个 Teammate 独立窗格，实时查看所有输出 | tmux 或 iTerm2 |
配置：
json
{ "teammateMode": "in-process" }或临时覆盖：
bash
claude --teammate-mode in-processauto（默认）：已在 tmux 会话中则用分屏，否则 in-process。
指定 Teammate 和模型
创建一个 4 人 Agent Team，并行重构这些模块。每个 Teammate 使用 Sonnet 模型。
计划审批（Plan Approval）
对复杂或有风险的任务，要求 Teammate 先规划再执行：
Spawn 一个 architect Teammate 重构认证模块。在做任何修改前需要计划审批。
流程：
- Teammate 在 read-only Plan 模式下工作，完成规划
- 发送计划审批请求给 Lead
- Lead 自主审查：批准 → Teammate 开始实施；拒绝（附反馈）→ Teammate 修订并重新提交
- 如需影响 Lead 判断，在 prompt 中给出标准：「只批准包含测试覆盖的计划」
任务分配与认领
共享任务列表状态：pending → in progress → completed
任务可有依赖：有未解决依赖的 pending 任务无法被认领，直到依赖完成。
- Lead 分配：告诉 Lead 把哪个任务分给哪个 Teammate
- 自主认领：Teammate 完成任务后自动认领下一个未分配的可用任务
- 文件锁防竞争：多个 Teammate 同时认领同一任务时，文件锁防止冲突
对话历史与通信
- Teammate 共享会话历史：团队中所有 Teammate 加入会话时，都会收到完整的对话历史
- 这与 subagents 不同（subagents 只收到主 Agent 发给它的内容）
- Teammate 可以直接相互发消息，无需通过 Lead
清理团队
# 优雅关闭一个 Teammate
shutdown teammate-name
# 清理整个团队（Lead 自动完成或手动）
# Lead 完成任务后自动尝试关闭所有 Teammate
7 大最佳实践
- 给 Teammate 足够上下文：spawn 时在 prompt 中包含相关背景
- 合适的团队规模：Token 消耗与 Teammate 数量近似成正比；从小团队开始
- 合理划分任务大小：任务太小（合并开销 > 收益）或太大（单个 Teammate 无法独立完成）都不好
- 等 Teammate 完成：在合并结果前让 Lead 等待所有 Teammate 完成
- 从研究和审查开始：Agent Teams 在探索/讨论场景下比直接代码修改更稳定
- 避免文件冲突：为 Teammate 分配独立的文件或模块，减少同一文件同时被多人修改
- 监控和引导：Lead 协调，但你随时可以直接与 Teammate 通信调整方向
常见问题排查
| 问题 | 解决方案 |
|---|---|
| Teammate 没有出现 | 检查 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 是否已设置 |
| 权限提示太多 | 给 Teammate 更精确的允许工具列表 |
| Teammate 遇到错误停止 | 直接与 Teammate 通信，指导继续 |
| Lead 在工作完成前关闭 | 指示 Lead 等待所有 Teammate 完成后再关闭 |
| 残留 tmux 会话 | 手动 tmux kill-session -t <name> 清理 |
原文：Agent Teams - Claude Code Docs | 来源：Anthropic 官方文档