Agent Teams 是 Claude Code 的实验性功能，让多个 Claude Code 实例协同工作。一个会话作为团队负责人，协调工作、分配任务、汇总结果；队友独立工作，各有自己的上下文窗口，可以直接相互通信。
⚠️ Agent Teams 目前是实验性功能，默认禁用，需要手动开启。
Agent Teams vs Subagents：如何选择？
两者都能并行化工作，但运作方式不同：
| 对比项 | Subagents | Agent Teams |
|---|---|---|
| 上下文 | 独立上下文窗口，结果汇报给调用者 | 独立上下文窗口，完全独立 |
| 通信 | 只能向主 Agent 汇报结果 | 队友可以直接互相通信 |
| 协调 | 主 Agent 管理所有工作 | 共享任务列表，自我协调 |
| 最适合 | 只关心结果的聚焦任务 | 需要讨论和协作的复杂工作 |
| Token 成本 | 较低：结果摘要回主上下文 | 较高：每个队友都是独立的 Claude 实例 |
选择法则：当你需要快速、专注的工作者汇报结果时用 Subagents；当队友需要共享发现、互相挑战并自主协调时用 Agent Teams。
开启 Agent Teams
在 settings.json 中设置环境变量：
json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}创建第一个 Agent Team
用自然语言告诉 Claude 创建团队并描述任务：
我正在设计一个帮助开发者跟踪代码库中 TODO 注释的 CLI 工具。
创建一个 Agent Team 从不同角度探索这个问题：
一个队友负责 UX，一个负责技术架构，一个充当魔鬼代言人。
Claude 自动创建团队、生成共享任务列表、分配任务，最后尝试在完成时清理团队。
显示模式
In-process 模式（默认）：
- 所有队友在主终端内运行
Shift+Down循环切换队友- 直接输入向当前队友发送消息
- 任何终端都支持，无需额外配置
Split-pane 模式（需要 tmux 或 iTerm2）：
- 每个队友拥有独立面板
- 同时看到所有人的输出
- 点击面板直接与对应队友交互
配置显示模式：
json
{ "teammateMode": "in-process" }或单次会话使用：
bash
claude --teammate-mode in-process指定队友数量和模型
创建一个有 4 个队友的团队来并行重构这些模块。
每个队友使用 Sonnet。
计划审批工作流
对于高风险任务，要求队友在实施前先提交计划：
派出一个架构师队友来重构认证模块。
要求在做任何修改前先获得计划批准。
工作流：
- 队友在只读计划模式下工作
- 完成计划后向负责人发送审批请求
- 负责人审查并批准（或拒绝并给出反馈）
- 被拒绝时，队友修改计划后重新提交
- 获批后退出计划模式，开始实施
任务分配机制
共享任务列表协调全队工作。任务有三种状态：待处理、进行中、已完成。
- 负责人分配：告诉负责人将哪个任务分给哪个队友
- 自主认领：队友完成一个任务后，自动认领下一个未分配、未阻塞的任务
任务认领使用文件锁防止多个队友同时抢同一任务。
实用场景示例
并行代码审查
创建一个 Agent Team 审查 PR #142。派出三个审查者：
- 一个专注安全影响
- 一个检查性能影响
- 一个验证测试覆盖率
让他们独立审查，然后汇总发现。
竞争假设调试
我们的 API 响应时间突然变慢了。
创建一个团队，三个队友分别测试不同的假设：
1. 数据库查询问题
2. 网络层问题
3. 代码逻辑问题
并行调查，谁先找到根因谁汇报。
架构原理
| 组件 | 职责 |
|---|---|
| 团队负责人 | 主 Claude Code 会话，创建团队、生成任务、协调工作 |
| 队友 | 独立的 Claude Code 实例，各自完成分配的任务 |
| 任务列表 | 队友认领和完成的共享工作条目 |
| 邮箱 | Agent 间通信的消息系统 |
存储位置：
- 团队配置：
~/.claude/teams/{team-name}/config.json - 任务列表：
~/.claude/tasks/{team-name}/
质量门控 Hooks
用 Hooks 在关键节点强制执行规则：
TeammateIdle：队友即将空闲时触发，返回退出码 2 可发送反馈并让队友继续工作TaskCompleted：任务即将标记完成时触发，返回退出码 2 可阻止完成并发送反馈
最佳实践
- 给队友足够上下文：每个队友从干净状态开始，记得在 Prompt 中提供必要背景
- 控制团队规模：3-5 个队友通常最优，团队越大协调开销越高
- 合理拆分任务：任务过小浪费协调成本，任务过大则队友无法并行
- 先研究再实施：让一个队友先做全局调查，再派其他队友实施
- 避免文件冲突：确保不同队友处理不同文件，防止写入冲突
- 主动监控和引导：不要完全放手，定期检查进展并在需要时重新引导
Token 成本注意
Agent Teams 消耗的 Token 远多于单个会话。每个队友都有独立的上下文窗口，成本随活跃队友数量线性增长。研究、审查和新功能开发值得这个额外成本；常规任务单个会话更经济。
原文：Orchestrate teams of Claude Code sessions | 来源：Claude Code 官方文档