Agent Teams 是 Claude Code 的实验性功能，让多个 Claude Code 实例作为团队协同工作。一个会话作为团队负责人，协调工作、分配任务、综合结果；队友各自独立工作，可以直接互发消息。
⚠️ Agent Teams 默认关闭，有已知限制（会话恢复、任务协调、关闭行为）。
何时用 Agent Teams
最强用例：
- 研究与审查：多个队友同时调查问题的不同方面，互相分享和挑战发现
- 新模块/功能开发：每个队友独立拥有不同的模块，互不干扰
- 竞争假设调试：队友并行测试不同理论，更快收敛到答案
- 跨层协调：前端/后端/测试各层变更，各由不同队友负责
不适合的情况：
- 顺序任务（A 必须等 B 完成）
- 同一文件的编辑（会冲突）
- 依赖关系复杂的工作
- 这些场景用单会话或 Subagents 更有效
启用 Agent Teams
json
// ~/.claude/settings.json 或项目 settings.json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}或在启动时设置环境变量：
bash
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude启动第一个 Agent Team
启用后，直接用自然语言告诉 Claude 你想要什么样的团队：
> 我在设计一个帮助开发者跟踪代码库 TODO 注释的 CLI 工具。
> 创建一个 Agent Team 从不同角度探索：
> 一个负责 UX，一个负责技术架构，一个充当唱反调的人。
Claude 会：
- 创建共享任务列表
- 为每个角色生成队友
- 让队友探索问题、互相挑战
- 综合各方发现
- 工作完成后尝试清理团队
负责人终端会列出所有队友和他们正在做的事。用 Shift+Down 循环切换队友，直接向他们发消息。
显示模式
| 模式 | 行为 | 要求 |
|---|---|---|
| in-process | 所有队友在主终端内运行，Shift+Down 切换 | 任意终端 |
| split panes | 每个队友有独立分栏，同时看到所有人的输出 | tmux 或 iTerm2 |
| auto（默认） | 已在 tmux 中用分栏，否则用 in-process | — |
json
// settings.json 设置默认模式
{ "teammateMode": "in-process" }
// 单次会话覆盖
claude --teammate-mode in-process分栏模式需要 tmux 或 iTerm2（启用 Python API）。
控制 Agent Team
指定队友数量和模型
> 创建一个有 4 个队友的团队并行重构这些模块，每个队友用 Sonnet。
要求队友先制定计划再执行
> 创建一个团队审查这个 PR，要求每个队友先制定计划，经过我批准后再开始实施。
队友在只读 Plan Mode 中工作，负责人批准后才能开始修改。
直接与单个队友对话
# Shift+Down 切换到目标队友，直接输入
> 你关于性能的发现很有意思，能深入分析一下数据库查询部分吗？
分配和认领任务
# 负责人分配任务
> 给安全审查员分配任务：审查所有 API 端点的输入验证
# 队友认领任务（队友也可以自主认领共享列表中的任务）
关闭队友
> 关闭 UX 审查员，它的工作已经完成了
清理整个团队
> 所有工作完成后，关闭所有队友并清理团队
用 Hooks 强制质量关卡
在 Agent Team 中，每个队友都可以触发 Hooks。可以用 Hooks 确保每个队友的代码都经过 Lint 检查：
json
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"command": "npm run lint --fix"
}]
}]
}
}内部架构
负责人：普通的 Claude Code 会话，通过 sessions_spawn 创建队友
队友：独立的 Claude Code 进程，各有自己的：
- Context 窗口（不共享主会话上下文）
- 工具访问（继承负责人的权限，可进一步限制）
- 通信能力（通过
sessions_send与其他队友直接通信）
共享任务列表：负责人维护一个所有人可见的任务列表，队友可以认领任务并标记完成。
权限模型：队友从负责人继承工具权限。用 --permission-mode plan 可以要求队友在修改前先获得批准。
实战案例
并行代码审查
> 对这个 PR 进行多维度审查：
> - 安全审查员：检查输入验证、SQL 注入、XSS 等安全问题
> - 性能审查员：分析算法复杂度、数据库查询效率、缓存机会
> - 测试审查员：评估测试覆盖率，找出缺少的边缘用例
> 三人并行工作，最终综合报告。
竞争假设调试
> 生产环境的内存泄漏还未找到原因。
> 创建一个调试团队，三个队友分别测试不同假设：
> - 假设 A：事件监听器未清理
> - 假设 B：循环引用导致 GC 无法回收
> - 假设 C：缓存无限增长
> 并行排查，谁先找到证据就汇报。
故障排查
| 问题 | 解决方案 |
|---|---|
| 队友不出现 | 确认已启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |
| 权限提示太多 | 负责人用 --dangerously-skip-permissions（谨慎）或预先批准常用命令 |
| 队友遇到错误停止 | 直接 Shift+Down 切换到队友，发消息引导它继续 |
| 负责人在工作完成前关闭 | 明确告诉负责人「等所有队友完成后再关闭」 |
| 孤立的 tmux 会话 | tmux ls 查找，tmux kill-session -t <name> 清理 |
原文：Orchestrate teams of Claude Code sessions | 来源：Anthropic 官方文档