Agent Teams 是 Claude Code 中让多个 Claude 实例像团队一样协作的实验性功能——一个 Lead 会话负责协调，Teammate 各自拥有独立上下文并可以直接互相通信。本文用官方文档给出的真实示例场景，演示从启用到实际协作的完整过程。
第一步：启用 Agent Teams
Agent Teams 默认是禁用的，需要显式设置环境变量：
// settings.json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}或者在 Shell 环境中直接导出：
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1第二步：用自然语言描述任务和团队角色
启用后，直接用自然语言描述任务和你想要的队友角色即可，官方给出的示例：
我在设计一个帮助开发者追踪代码库中 TODO 注释的 CLI 工具。
生成三个队友从不同角度探索这个问题：
一个负责 UX，一个负责技术架构，一个唱反调。
这个例子之所以有效，是因为三个角色是独立的，可以互不等待地各自探索问题。
第三步：Claude 自动完成的工作
从这里开始，Claude（作为 Lead）会：
- 生成一个共享任务列表
- 为每个视角生成对应的 Teammate
- 让它们各自探索问题
- 完成后综合汇总各方发现
第四步：在 Lead 终端中管理团队
Lead 的终端会在提示输入框下方的 Agent Panel 中列出所有队友，支持这些操作：
↑ / ↓：选择一个队友
Enter：打开选中队友的转录记录，直接向它发消息
Esc：中断选中队友当前的这一轮
空闲行的显示逻辑（v2.1.199 起）
只要还有任何队友或 Subagent 在工作，一个已经空闲的队友的行会继续保留在面板中，方便你随时选中查看转录或派发新工作。等到面板里所有 Agent 都空闲后，空闲的行会在 30 秒后隐藏，队友下一轮工作时再次出现——隐藏期间该队友依然在运行、依然可以被寻址。
版本差异提示：v2.1.181 到 v2.1.198 之间，空闲行会在自己那一轮结束30 秒后就隐藏（即使其他队友还在工作）；v2.1.181 之前的版本，空闲行完全不会隐藏。
超过三个空闲队友时的折叠显示
当同时有超过三个队友空闲时，第三个之后的行会折叠成一行，显示折叠了多少个队友，比如五个空闲时显示 2 idle agents。选中这一行按 Enter 展开，按 Esc 重新折叠。正在工作的队友、失败的队友、以及你正在查看的队友，始终各自保留独立的行，不会被折叠。
第五步：选择显示模式
Agent Teams 支持两种显示模式：
- In-process（默认）：所有队友在你的主终端内运行。用方向键在 Agent Panel 中选择队友，按 Enter 查看并直接输入消息。任何终端都能用，无需额外配置
- Split panes（分屏）：每个队友获得独立的面板，可以同时看到所有人的输出，点进某个面板直接交互。需要 tmux 或 iTerm2
// 显式设置为分屏模式（需要 tmux 环境或 iTerm2 + it2 CLI）
{
"teamDisplayMode": "auto"
}版本提示：v2.1.179 之前默认是
"auto"，所以从旧版本升级的会话，如果之前是自动分屏的，现在会保持单终端模式，除非你显式设置为"auto"。"auto"模式下，如果你本来就在 tmux 会话中，或者用的是安装了it2CLI 的 iTerm2，会自动启用分屏，否则回退到 in-process 模式。
使用建议
根据官方指南，Agent Teams 最适合这几类场景：
- 研究与评审：多个队友同时调查问题的不同侧面，然后互相分享和挑战彼此的发现
- 新模块/新功能：每个队友独立负责一块，互不干扰
- 多假设并行调试：队友并行测试不同的假设理论，更快收敛到正确答案
- 跨层协调：一个改动横跨前端、后端和测试，各自由不同队友负责
需要避免的场景：Agent Teams 会带来额外的协调开销，并且比单一会话消耗明显更多的 Token。对于顺序性任务、需要编辑同一个文件、或者依赖关系很多的工作，单一会话或 Subagents 效果更好。
避免文件冲突的关键提醒
Agent Teams 不会像 Agent View 那样自动把队友隔离到独立的 Worktree 中，所以如果任务会涉及修改文件，你需要自己主动划分工作范围——确保每个队友负责一组不同的文件，避免多个队友同时编辑同一个文件产生冲突。
总结
Agent Teams 的价值在于让多个视角真正互相对话，而不只是各自独立汇报给你——这对需要「集思广益」「互相挑战假设」的探索性任务特别有价值。但它是实验性功能、Token 成本更高，且不会自动处理文件冲突，适合谨慎评估后用在真正需要多视角讨论的场景，而不是所有并行任务的默认选择。
来源：Orchestrate teams of Claude Code sessions — Claude Code 官方文档，Anthropic