Appearance
Agent Teams（代理团队）
实验性功能，默认关闭。 通过在 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
json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}或设置环境变量：
bash
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。
json
{
"teammateMode": "in-process"
}或通过标志指定：
bash
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 可发送反馈让队员继续工作TaskCompleted：任务被标记为完成时运行，返回退出码 2 可阻止完成并发送反馈
实战示例
并行代码审查
单个审查者往往集中于一类问题，把审查标准分成独立领域，可以同时深度覆盖安全性、性能和测试覆盖率：
创建一个 Agent 团队审查 PR #142。生成三个审查者：
- 一个专注于安全影响
- 一个检查性能影响
- 一个验证测试覆盖率
让他们各自审查并汇报发现。用竞争假设调试
当根本原因不明确时，强制队员互相质疑对方的理论可以避免"第一个合理解释"偏差：
用户报告应用发送一条消息后就退出，而不是保持连接。
生成 5 个 Agent 队员研究不同假设。让他们互相讨论，
尝试反驳彼此的理论，像科学辩论一样。
把出现的共识更新到 findings 文档中。最佳实践
给队员足够的上下文
队员不继承领导的对话历史，需要在生成提示词中包含任务特定细节：
生成一个安全审查员队员，提示词为："审查 src/auth/ 中的认证模块
是否有安全漏洞，专注于 Token 处理、会话管理和输入验证。
应用使用存储在 httpOnly Cookie 中的 JWT Token。
报告任何问题并附上严重性评级。"控制团队规模
大多数工作流从 3-5 个队员开始，每个队员 5-6 个任务可以保持高效率。
- Token 费用线性增长
- 更多队员增加协调开销
- 超过一定数量后，额外的队员不能成比例地加速工作
合理拆分任务
- 太小：协调开销超过收益
- 太大：队员长时间工作而没有检查点，增加返工风险
- 恰好：自包含的单元，产生明确的交付物（一个函数、一个测试文件、一次审查）
避免文件冲突
两个队员编辑同一个文件会导致覆盖。确保每个队员拥有不同的文件集合。
当前限制
- 无法恢复 in-process 队员：
/resume和/rewind不能恢复 in-process 队员 - 任务状态可能滞后：队员有时无法标记任务为完成，导致阻塞依赖任务
- 关闭可能较慢：队员完成当前请求后才关闭
- 每会话只有一个团队：领导只能管理一个团队，创建新团队前需先清理
- 不支持嵌套团队：队员无法生成自己的队员
- 领导固定不变：无法将队员提升为领导