Agent Teams（代理团队）

Agent Teams 是 Claude Code 的实验性功能，让多个独立的 Claude Code 实例协同工作。一个领导会话负责协调，队员各有独立上下文，可直接互相通信——这是与子代理的核心区别。适合并行研究、跨模块开发、竞争假设调试等需要"让不同角色深度讨论"的场景。启用方式：在 settings.json 的 env 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，然后用自然语言告诉 Claude 创建团队即可。

实验性功能，默认关闭。 在 settings.json 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用。

Agent Teams 让多个 Claude Code 实例协同工作：一个会话作为团队领导，协调工作、分配任务、汇总结果；队员独立运行，各有自己的上下文窗口，并可以直接通信。

需要 Claude Code v2.1.32 或更高版本，运行 claude --version 检查。

与子代理的区别

子代理只能向主 Agent 汇报结果，无法互相通信。Agent Teams 中，队员共享任务列表，可以互相认领任务和直接通信。

	子代理	Agent Teams
上下文	独立上下文，结果返回给调用者	独立上下文，完全独立
通信	只向主代理汇报结果	队员可直接互相通信
协调	主代理管理所有工作	共享任务列表，自主协调
最适合	只需要结果的专注任务	需要讨论和协作的复杂工作
Token 费用	较低：结果汇总回主上下文	较高：每个队员是独立的 Claude 实例

用子代理：需要快速、专注的执行者。 用 Agent Teams：队员需要共享发现、互相挑战、自主协调。

启用 Agent Teams

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

或设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

开始第一个团队

启用后，用自然语言告诉 Claude 创建一个团队：

我正在设计一个帮助开发者跟踪代码库 TODO 注释的 CLI 工具。
创建一个 Agent 团队从不同角度探索这个问题：
一个负责用户体验，一个负责技术架构，一个扮演唱反调的角色。

Claude 创建团队后，领导终端会列出所有队员和他们的工作内容。使用 Shift+Down 在队员间切换并直接发消息。

最佳使用场景

研究和审查：多个队员同时研究问题的不同方面，然后分享和质疑彼此的发现。

新模块或功能：队员各自负责独立的部分，互不干扰。

调试竞争假设：队员并行测试不同理论，更快收敛到答案。

跨层协调：跨越前端、后端和测试的变更，每个队员负责不同层。

Agent Teams 增加协调开销，消耗的 Token 显著多于单个会话。对于顺序任务、同文件编辑或依赖关系多的工作，单个会话或子代理更有效。

显示模式

in-process 模式：所有队员在主终端内运行，使用 Shift+Down 切换，无需额外配置。

split-panes 模式：每个队员有独立窗格，同时看到所有输出，需要 tmux 或 iTerm2。

在全局配置 ~/.claude.json 中设置：

{
  "teammateMode": "in-process"
}

或通过标志临时覆盖：

claude --teammate-mode in-process

控制团队

指定队员和模型

创建一个 4 人团队并行重构这些模块，每个队员使用 Sonnet。

要求计划审批

对于复杂或有风险的任务，可以要求队员在实施前先规划：

生成一个负责重构认证模块的架构师队员，要求在做任何修改前先审批计划。

队员完成规划后向领导发送审批请求，领导审查后批准或拒绝并提供反馈。

你可以在提示词中给领导决策标准，如：

• "只批准包含测试覆盖的计划"
• "拒绝修改数据库 Schema 的计划"

直接与队员通信

• in-process 模式：Shift+Down 切换到队员，直接输入发消息；按 Enter 进入队员会话，Escape 中断当前轮次
• split-pane 模式：点击队员窗格直接交互

关闭队员

让研究员队员关闭

清理团队

清理团队

始终由领导执行清理，不要让队员执行清理，否则可能留下不一致的状态。

架构

组件	角色
团队领导	创建团队、生成队员、协调工作的主 Claude Code 会话
队员	各自处理分配任务的独立 Claude Code 实例
任务列表	队员认领和完成的共享任务列表
邮箱	代理间的通信系统

团队配置存储在 ~/.claude/teams/{team-name}/config.json，任务列表在 ~/.claude/tasks/{team-name}/。

使用 Hooks 强制质量门控

使用 Hooks 在队员完成工作或任务创建/完成时强制执行规则：

• TeammateIdle：队员即将闲置时运行，返回退出码 2 可发送反馈让队员继续工作
• TaskCreated：任务被创建时运行，返回退出码 2 可阻止创建并发送反馈
• TaskCompleted：任务被标记为完成时运行，返回退出码 2 可阻止完成并发送反馈

使用子代理定义作为队员

生成队员时可以引用任何子代理定义（项目级、用户级、插件级或 CLI 定义）。这样你可以定义一次角色（如 security-reviewer 或 test-runner），同时在子代理委托和 Agent Teams 队员中复用：

生成一个使用 security-reviewer 代理类型的队员来审计 auth 模块。

队员遵守该定义的工具白名单和模型，定义的正文作为附加指令追加到队员的系统提示中（而非替换）。团队协调工具（如 SendMessage 和任务管理工具）即使在 tools 限制其他工具时也始终可用。

实战示例

并行代码审查

单个审查者往往集中于一类问题，把审查标准分成独立领域，可以同时深度覆盖安全性、性能和测试覆盖率：

创建一个 Agent 团队审查 PR #142。生成三个审查者：
- 一个专注于安全影响
- 一个检查性能影响
- 一个验证测试覆盖率
让他们各自审查并汇报发现。

用竞争假设调试

当根本原因不明确时，强制队员互相质疑对方的理论可以避免"第一个合理解释"偏差：

用户报告应用发送一条消息后就退出，而不是保持连接。
生成 5 个 Agent 队员研究不同假设。让他们互相讨论，
尝试反驳彼此的理论，像科学辩论一样。
把出现的共识更新到 findings 文档中。

最佳实践

给队员足够的上下文

队员不继承领导的对话历史，需要在生成提示词中包含任务特定细节：

生成一个安全审查员队员，提示词为："审查 src/auth/ 中的认证模块
是否有安全漏洞，专注于 Token 处理、会话管理和输入验证。
应用使用存储在 httpOnly Cookie 中的 JWT Token。
报告任何问题并附上严重性评级。"

控制团队规模

大多数工作流从 3-5 个队员开始，每个队员 5-6 个任务可以保持高效率。

• Token 费用线性增长
• 更多队员增加协调开销
• 超过一定数量后，额外的队员不能成比例地加速工作

合理拆分任务

• 太小：协调开销超过收益
• 太大：队员长时间工作而没有检查点，增加返工风险
• 恰好：自包含的单元，产生明确的交付物（一个函数、一个测试文件、一次审查）

避免文件冲突

两个队员编辑同一个文件会导致覆盖。确保每个队员拥有不同的文件集合。

故障排查

队员没有出现

• in-process 模式下，队员可能已在运行但不可见，按 Shift+Down 循环切换
• 检查任务是否足够复杂，Claude 根据任务决定是否生成队员
• split-panes 模式：确认 tmux 已安装：which tmux；iTerm2 需要安装 it2 CLI 并在偏好设置中启用 Python API

权限确认太多

在权限设置中预批准常见操作，可减少队员弹出的中断请求。

队员遇到错误后停止

用 Shift+Down 切换到该队员查看输出，然后直接给它更多指令，或生成替代队员继续工作。

领导在工作完成前关闭

告诉领导继续工作，或在生成提示词中说明"等队员完成任务后再继续"。

残留 tmux 会话

清理团队后若有残留 tmux 会话：

tmux ls
tmux kill-session -t <session-name>

当前限制

• 无法恢复 in-process 队员：/resume 和 /rewind 不能恢复 in-process 队员；恢复后领导可能向不存在的队员发消息，需重新生成
• 任务状态可能滞后：队员有时无法标记任务为完成，导致阻塞依赖任务；可手动更新状态或让领导催促队员
• 关闭可能较慢：队员完成当前请求或工具调用后才关闭
• 每会话只有一个团队：领导只能管理一个团队，创建新团队前需先清理
• 不支持嵌套团队：队员无法生成自己的队员，只有领导可以管理团队
• 领导固定不变：无法将队员提升为领导或转让领导权
• 权限在生成时确定：所有队员以领导的权限模式启动，生成后可更改，但无法在生成时为每个队员独立设置
• split-panes 需要 tmux 或 iTerm2：不支持 VS Code 集成终端、Windows Terminal 或 Ghostty

相关资源

• 子代理：更轻量的任务委托方式
• 常见工作流：并行会话工作流（Git worktrees）
• Hooks：强制质量门控

常见问题

Q: claude code 如何使用 agent 功能？

首先启用实验性功能（设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1），然后在 Claude Code 会话中用自然语言指令创建团队，例如“创建一个3人团队来研究这个问题”。创建后，可通过共享任务列表协调工作，并使用快捷键在队员间切换和通信。

Q: claude code agent teams 怎么开启？

有两种开启方式：一是在 VSCode 的 settings.json 的 env 部分添加 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"；二是在终端中执行 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 设置环境变量。需要 Claude Code v2.1.32 或更高版本。

Q: claude code 多代理协作有什么使用场景？

主要适用于四大场景：1) 研究与审查（多角度深度分析）；2) 新功能并行开发（队员各负责独立模块）；3) 调试竞争假设（并行测试不同理论）；4) 跨层协调（如前端、后端、测试同步变更）。对于简单顺序任务，建议使用单个会话或子代理。

Q: claude code agent 和子代理有什么区别？

主要区别在于协作方式：子代理独立执行任务后只向主代理汇报结果，无法互相通信，适合专注性任务；Agent Teams 的队员拥有独立上下文，可以共享任务列表、直接相互通信和自主协调，适合需要讨论和复杂协作的工作，但 Token 消耗更高。

Q: 如何控制 claude code 中的 agent 队员？

你可以：1) 指定队员数量和使用的模型；2) 要求队员在实施前提交计划供审批；3) 使用 Shift+Down 直接与任一队员对话；4) 通过指令让特定队员关闭；5) 最终由团队领导执行“清理团队”指令来结束整个协作。