"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
Agent Teams 让你可以协调多个 Claude Code 实例一起干活。一个会话当老大，协调工作、分配任务、综合结果。小弟们独立工作，各自在自己的上下文窗口里，还能直接互相唠嗑。
跟子代理（Subagents）不同（子代理在单个会话里运行，只能向主代理报告），你还可以直接跟单个小弟互动，不用经过老大。
本文档涵盖：
• 何时用 Agent Teams，包括最佳用例及与子代理的对比 • 启动团队 • 控制小弟们，包括显示模式、任务分配和委托 • 并行工作的最佳实践
何时用 Agent Teams
Agent Teams 在并行探索能增加真正价值的任务中最有效。最强的用例包括：
• 研究和审查 —— 多个小弟可以同时调查问题的不同方面，然后分享和挑战彼此的发现 • 新模块或功能 —— 小弟们可以各自拥有独立的部分，互不干扰 • 带竞争假设的调试 —— 小弟们并行测试不同理论，更快找到答案 • 跨层协调 —— 跨越前端、后端和测试的更改，每个由不同小弟负责
Agent Teams 增加协调开销（你敢用Opus4.6开Agent Teams么🤣），比单个会话用显著增加 token消耗。它们在小组可以独立运作时效果最佳。对于顺序任务、同一文件编辑或有很多依赖的工作，单个会话或子代理更有效。
与子代理对比
Agent Teams 和子代理都可以让你并行工作，但运作方式不同。根据你的工作者是否需要互相通信来选择：
| 上下文 | ||
| 通信 | ||
| 协调 | ||
| 最适合 | ||
| Token 成本 |
当你需要快速、专注的工作者报告结果时用子代理。当小组需要分享发现、互相挑战和自我协调时用 Agent Teams。
启用 Agent Teams
Agent Teams 默认禁用。通过将 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量设置为 1 来启用，可以在 shell 环境中或通过 settings.json：
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}启动你的第一个 Agent Team
启用 Agent Teams 后，告诉 Claude 创建一个 Agent Team，用自然语言描述任务和你想要的团队结构。Claude 根据你的提示创建团队、生成小弟并协调工作。
这个示例效果很好，因为三个角色是独立的，可以在不等待彼此的情况下探索问题：
Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.
(创建一个 Agent Team 从不同角度探索：一个负责 UX，一个负责技术架构，一个扮演魔鬼代言人。)
从那里，Claude 创建一个带有共享任务列表的团队，为每个视角生成小弟，让他们探索问题，综合发现，并在完成后尝试清理团队。
老大的终端列出所有小弟及其工作内容。使用 Shift+Up/Down 选择小弟并直接给他们发消息。
控制你的 Agent Team
用自然语言告诉老大你想要什么。它根据你的指示处理团队协调、任务分配和委托。
选择显示模式
Agent Teams 支持两种显示模式：
• 进程内模式 —— 所有小弟在你的主终端内运行。使用 Shift+Up/Down 选择小弟并直接输入发消息。适用于任何终端，无需额外设置。 • 分屏模式 —— 每个小弟有自己的窗格。你可以同时看到所有人的输出，点击窗格直接互动。需要 tmux 或 iTerm2。
默认是 "auto"，如果你已经在 tmux 会话中运行则使用分屏，否则使用进程内模式。
要对单个会话强制使用进程内模式，传递标志：
claude --teammate-mode in-process
指定小弟和模型
Claude 根据你的任务决定生成多少 teammate，或者你可以准确指定你想要什么：
Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate.
(创建一个 4 人团队并行重构这些模块。每个成员用 Sonnet。)
要求 teammate 计划审批
对于复杂或有风险的任务，你可以要求 teammate 在实施前计划。teammate 在只读计划模式下工作，直到 lead 批准他们的方法：
Spawn an architect teammate to refactor the authentication module. Require plan approval before they make any changes.
(生成一个架构师 teammate 来重构认证模块。在他们做任何更改之前要求计划审批。)
当 teammate 完成计划时，它会向 lead 发送计划审批请求。老大审查计划并批准或拒绝并提供反馈。
使用委托模式
没有委托模式时，老大有时会自己开始实施任务，而不是等待小弟完成。委托模式通过将老大限制为仅协调工具来防止这种情况。按 Shift+Tab 切换到委托模式。
直接跟小弟对话
每个小弟是一个完整的、独立的 Claude Code 会话。你可以直接给任何小弟发消息：
• 进程内模式： 使用 Shift+Up/Down 选择小弟，然后输入发送消息。按 Enter 查看小弟的会话，然后按 Escape 中断他们当前的回合。按 Ctrl+T 切换任务列表。 • 分屏模式： 点击小弟的窗格直接与其会话互动。
分配和认领任务
共享任务列表协调团队的工作。老大创建任务，小弟完成。任务有三种状态：待处理、进行中、已完成。任务也可以依赖其他任务。
老大可以显式分配任务，或者小弟可以在完成任务后自行认领。
关闭小弟
要优雅地结束 teammate 的会话：
Ask the researcher teammate to shut down
(让研究员 teammate 关闭)
lead 发送关闭请求。teammate 可以批准并优雅退出，或拒绝并解释原因。
清理团队
完成后，让 lead 清理：
Clean up the team
(清理团队)
这会移除共享的团队资源。当老大运行清理时，它会检查活跃的小弟，如果还有在运行的则失败，所以要先关闭他们。
Agent Teams 怎么运作
架构
Agent Team 包括：
• 老大： 创建团队、生成小弟和协调工作的主 Claude Code 会话 • 小弟： 各自处理分配任务的独立 Claude Code 实例 • 任务列表： 小弟认领和完成的工作项共享列表 • 邮箱： 代理之间通信的消息系统
系统自动管理任务依赖。团队和任务本地存储：
• 团队配置： ~/.claude/teams/{team-name}/config.json• 任务列表： ~/.claude/tasks/{team-name}/
上下文和通信
每个小弟有自己的上下文窗口。生成时，小弟加载与常规会话相同的项目上下文：CLAUDE.md、MCP 服务器和技能。老大的对话历史不会传递过来。
小弟如何分享信息：
• 自动消息传递： 当小弟发送消息时，自动传递给接收者 • 空闲通知： 当小弟完成并停止时，自动通知老大 • 共享任务列表： 所有代理可以看到任务状态并认领可用工作
Token 使用
Agent Teams 比单个会话用显著增加token消耗。每个小弟有自己的上下文窗口，token 使用量随活跃小弟数量增加而增加。对于研究、审查和新功能工作，额外的 token 通常是值得的。对于常规任务，单个会话更具成本效益。
用例示例
运行并行代码审查
单个审查者倾向于一次专注于一种类型的问题。将审查标准拆分为独立领域意味着安全、性能和测试覆盖同时得到彻底关注。
Create an agent team to review PR #142. Spawn three reviewers: one focused on security implications, one checking performance impact, one validating test coverage. Have them each review and report findings.
(创建一个 Agent Team 来审查 PR #142。生成三个审查员：一个专注于安全影响，一个检查性能影响，一个验证测试覆盖。让他们各自审查并报告发现。)
用竞争假设调查
当根本原因不清楚时，单个 agent 倾向于找到一个看似合理的解释就停止寻找。
Users report the app exits after one message instead of staying connected. Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each other's theories, like a scientific debate. Update the findings doc with whatever consensus emerges.(用户报告应用在一条消息后退出而不是保持连接。生成 5 个 Agent teammates 调查不同的假设。让他们互相交谈，试图反驳彼此的假设，就像科学辩论一样。用出现的任何共识更新发现文档。)
最佳实践
给小弟足够的上下文
小弟自动加载项目上下文，但不继承老大的对话历史。在生成提示中包含任务特定的细节。
适当调整任务大小
• 太小： 协调开销超过收益 • 太大： 小弟工作太久没有检查，增加浪费努力的风险 • 刚好： 自成一体的单元，产生清晰的交付物
等待小弟完成
有时 lead 自己开始实施任务，而不是等待 teammate 完成。如果你注意到这种情况：
Wait for your teammates to complete their tasks before proceeding
(等待你的 teammates 完成任务后再继续)
避免文件冲突
两个小弟编辑同一文件会导致覆盖。拆分工作让每个小弟拥有不同的文件集。
监控和引导
检查小弟的进度，重定向不起作用的方法，并随着进展综合发现。
限制
Agent Teams 是实验性的。当前限制：
• 进程内小组成员不支持会话恢复： /resume 和 /rewind 不会恢复进程内小弟 • 任务状态可能滞后： 小弟有时无法标记任务完成 • 关闭可能很慢： 小弟在关闭前完成当前请求 • 每会话一个团队： 一个老大一次只能管理一个团队 • 不支持嵌套团队： 小弟不能生成自己的团队 • 老大固定： 创建团队的会话在其生命周期内是老大 • 分屏需要 tmux 或 iTerm2： 不支持 VS Code 集成终端、Windows Terminal 或 Ghostty
