我不明白为什么现在还没人这么做。

Anthropic 自己的 Claude Code 文档就展示了如何运行一整个 Claude 团队，而 Opus 5.5 只负责处理计划和合并

核心理念：在 Claude Code 中组建 agent 团队

一个主控，各自的队友运行在独立的上下文窗口中，共享一份任务列表，彼此直接通信

主控：Opus 5.5 设为 high 档，负责拆分任务、编写任务、最终合并 构建者：Sonnet 5.5，一个负责 client/，一个负责 api/，绝不碰同一个文件 对抗者：Fable 5.1，从不写代码，只在三个节点出现：

→ 接口锁定之前：双方是否认同这份契约？ → 测试第二次失败时：是修好了，还是只是被掩盖了？ → 任务标记为完成之前：什么东西会被它打破？

Sonnet 5.5 构建。Fable 5.1 攻击。Opus 5.5 合并

Jev 工程是同一招式再下沉一层：那些不需要思考者的分叉（该用哪个文件、哪个工具、重试还是停止）在半秒内交给 Jev，团队只讨论真正有分歧的地方

打开它，然后用自然语言启动团队：

“Spawn three teammates: ux and backend on Sonnet, an adversary on Fable”

• 完整团队配置

Opus 5.5 设为 high 档，主导本次会话 ux 使用 Sonnet 5.5，负责 client/ backend 使用 Sonnet 5.5，负责 api/ 对抗者使用 Fable 5.1，不负责任何文件，审查一切 共享任务列表，带文件锁定，直接通信，主控不居中干预

把这个团队配置和下面的提示词粘贴进 Claude Code ↓

“Set up agent teams for this repo:

1. 在 ~/.claude/settings.json 的 env 下添加 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，并将 effortLevel 设为 high

2. 在 ~/.claude/agents 下，为各个队友起草三份 subagent 定义

ux 和 backend 使用 model: sonnet，各自限制在自己的文件夹内 adversary 使用 model: fable 且只读工具，唯一职责是攻击契约、反复失败的测试和完成声明 跳过已存在的定义并列出来

3. 添加一个 TaskCompleted 钩子，在对抗者签署批准之前阻止任务完成，并在 CLAUDE.md 中加入一条规则：不允许两个队友编辑同一个文件

4. 找出任何可能覆盖此配置的内容（CLAUDE_CODE_SUBAGENT_MODEL、CLAUDE_CODE_SUBAGENT_MODEL_FORCE、CLAUDE_CODE_EFFORT_LEVEL）。报告它们，但不要做任何修改

先以 diff 形式展示每一处改动。在我说 go 之前不要做任何编辑。“

↳ https://code.claude.com/docs/en/agent-teams…

编排多个 Claude Code 会话组成的团队 - Claude Code 文档

来源：https://code.claude.com/docs/en/agent-teams Agent teams 让你可以协调多个协同工作的 Claude Code 实例。其中一个会话担任团队主控，负责协调工作、分配任务并综合结果。队友各自独立工作，运行在各自的上下文窗口中，并直接相互通信。你也可以直接与任何队友对话，无需经过主控。在搭建团队之前，请先确认更轻量的方案是否够用。subagents (https://code.claude.com/docs/en/sub-agents) 在单个会话内工作，配合跨会话消息传递 (https://code.claude.com/docs/en/cross-session-messaging)，Claude 可以在你自己运行的各个会话之间传递发现。

何时使用 agent teams

Agent teams 在并行探索能带来真正价值的任务中效果最好。完整场景见用例示例 (https://code.claude.com/docs/en/agent-teams#use-case-examples)。最强的用例包括：

• 研究与评审：多个队友可以同时调查问题的不同方面，然后分享并相互质疑彼此的发现
• 新模块或新功能：每个队友各自负责独立的部分，互不干扰
• 带竞争假设的调试：队友并行验证不同理论，更快收敛到答案
• 跨层协调：涉及前端、后端和测试的改动，每个部分由不同的队友负责

Agent teams 会增加协调开销，消耗的 token 也显著多于单个会话。当队友能够独立运作时效果最佳。对于顺序性任务、同一文件的编辑，或依赖关系繁多的工作，单个会话或 subagents (https://code.claude.com/docs/en/sub-agents) 更为有效。

与 subagents 的对比

Agent teams 和 subagents (https://code.claude.com/docs/en/sub-agents) 都能让你并行化工作，但运作方式不同。如果你想在没有团队的情况下让多个独立会话相互传递消息，请参阅跨会话消息传递 (https://code.claude.com/docs/en/cross-session-messaging)。

子代理与 agent team 架构对比图。Subagents 由主代理生成、执行工作并把结果汇报回去。Agent teams 通过共享任务列表进行协调，队友之间直接相互通信。

Subagents 把结果汇报给主代理。而在 agent teams 中，队友共享一份任务列表、认领工作，并直接相互通信。

当你需要快速、专注且能汇报结果的执行者时，使用 subagents。当队友需要共享发现、相互质疑并自行协调时，使用 agent teams。

启用 agent teams

Agent teams 默认是禁用的。启用方式是将 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量设置为 1，可以设在 shell 环境中，也可以通过 settings.json (https://code.claude.com/docs/en/settings) 设置：

启用 agent teams 也会改变普通的委派行为。Claude 可能会自行命名一个 subagent (https://code.claude.com/docs/en/sub-agents#subagent-names)，而在启用 agent teams 后，Claude 命名的 subagent 会以队友的形式启动，因此即使你没有要求组建团队，也可能形成团队。更多内容请参阅 Claude 如何启动 agent teams (https://code.claude.com/docs/en/agent-teams#how-claude-starts-agent-teams)；若要关闭该行为，请参阅 Claude 生成队友而非 subagents (https://code.claude.com/docs/en/agent-teams#claude-spawns-teammates-instead-of-subagents)。生成队友还需要交互式会话。在非交互模式 (https://code.claude.com/docs/en/headless) 下使用 -p 标志时（包括 Agent SDK 会话），Claude 不会生成队友，即使启用了 agent teams，Claude 命名的 subagent 也会以普通 subagent (https://code.claude.com/docs/en/sub-agents) 的方式运行。

启动你的第一个 agent team

启用 agent teams 之后，用自然语言描述任务和你想要的队友即可。Claude 会生成他们，并根据你的提示协调工作。这个示例效果很好，因为三个角色彼此独立，可以各自探索问题而无需等待对方：

随后，Claude 会填充一份共享任务列表 (https://code.claude.com/docs/en/interactive-mode#task-list)（该会话需要具备任务工具 (https://code.claude.com/docs/en/tools-reference#task-tool-availability)），为每个视角生成队友，让他们探索问题，并在完成时综合各路发现。Claude 有时可能会使用 subagents (https://code.claude.com/docs/en/sub-agents) 而不是创建团队。Subagents 会和队友一起出现在同一个 agent 面板中，因此仅凭面板无法确认团队是否已形成。如果 Claude 生成的是 subagents，请再次请求并明确要求 agent team。

主控的终端会在提示输入框下方的 agent 面板中列出队友。在该面板中：

• 上下方向键：选择队友
• Enter：打开所选队友的记录并直接向其发送消息
• Escape：清除选择。当你正在查看某个队友的记录时，Escape 会中断该队友当前的回合

只要有任意一个队友或 subagent 仍在工作，空闲队友的行就会保留在面板中，方便你选中以查看其记录或追加任务。当面板中的所有 agent 都处于空闲状态时，空闲行会在 30 秒后隐藏，下次该队友进入回合时重新显示；隐藏期间该队友仍保持运行且可寻址。

当同时有超过三个队友处于空闲状态时，第一个之后的行会折叠为一行，显示被折叠的队友数量，例如五人空闲时显示 2 idle agents。选中后按 Enter 展开折叠的行，或再次按 Esc 折叠回去。正在工作的队友、失败的队友，以及你正在查看的队友，始终各自保留独立的行。

如果你想让每个队友都拥有独立的分屏窗格，请参阅选择显示模式 (https://code.claude.com/docs/en/agent-teams#choose-a-display-mode)。

控制你的 agent team

用自然语言告诉主控你想要什么。它会根据你的指令负责团队协调、任务分配和委派。

选择显示模式

Agent teams 支持两种显示模式：

• 进程内（in-process）：所有队友都在你的主终端内运行。使用 agent 面板中的上下方向键选择队友，按 Enter 查看，直接输入即可发送消息。适用于任何终端，无需额外配置。
• 分屏窗格（split panes）：每个队友拥有自己的窗格。你可以同时看到所有人的输出，并点击某个窗格直接交互。需要 tmux 或 iTerm2。

默认值为 "in-process"。设为 "auto" 可在你已经处于 tmux 会话中运行时，或你的终端是 iTerm2 且已安装 it2 CLI 时启用分屏窗格，否则回退为进程内模式。"tmux" 设置会启用分屏窗格模式，并根据你的终端自动检测使用 tmux 还是 iTerm2。设为 "iterm2" 则明确使用 iTerm2 原生分屏窗格。此模式需要 it2 CLI (https://github.com/mkusaka/it2)，若 it2 缺失会显示包含安装命令的错误提示。当你的终端是 iTerm2 且 tmux 可作为后备方案时，安装 it2 或切换到 tmux 的设置提示会在 "auto" 或 "tmux" 模式下出现。

要覆盖默认值，可在 ~/.claude/settings.json 中设置 teammateMode (https://code.claude.com/docs/en/settings-reference#teammatemode)：

要为单次会话设置模式，可以作为标志传入：

--teammate-mode 标志是实验性的，不出现在 claude --help 中。分屏窗格模式需要 tmux (https://github.com/tmux/tmux/wiki) 或 iTerm2 且已安装 it2 CLI (https://github.com/mkusaka/it2)。手动安装方法：

• tmux：通过系统的包管理器安装。平台相关说明请参阅 tmux wiki (https://github.com/tmux/tmux/wiki/Installing)。
• iTerm2：安装 it2 CLI (https://github.com/mkusaka/it2)，然后在 iTerm2 → Settings → General → Magic → Enable Python API 中启用 Python API。

指定队友和模型

Claude 会根据你的任务决定生成多少个队友，你也可以精确指定：

Claude Code 按以下顺序中第一个适用的来源选择每个队友的模型：

1. 你的生成提示词中为该队友指定的模型。
2. 对于由 subagent 定义 (https://code.claude.com/docs/en/agent-teams#use-subagent-definitions-for-teammates) 生成的队友，使用该定义中的 model，其中 inherit 表示采用主控的模型。
3. CLAUDE_CODE_SUBAGENT_MODEL (https://code.claude.com/docs/en/model-config#environment-variables)，前提是它被设置为 inherit 以外的任何值。
4. 主控当前的模型。

如果你设置了 CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (https://code.claude.com/docs/en/sub-agents#run-every-subagent-on-one-model)，则前两个来源不再生效。此时 Claude Code 会从 CLAUDE_CODE_SUBAGENT_MODEL（当其设置为 inherit 以外的值时）选择每个队友的模型，否则使用主控当前的模型。需要 Claude Code v2.1.257 或更高版本。在 v2.1.251 之前，CLAUDE_CODE_SUBAGENT_MODEL 在此顺序中排在最前面。

Claude Code 会用所选模型与你组织的 availableModels (https://code.claude.com/docs/en/model-config#restrict-model-selection) 白名单进行核对。当白名单屏蔽某个值时，Claude Code 会替换为其他模型：

• 族别名（family alias），如 opus：在 Anthropic API 和 AWS 上的 Claude Platform 中，Claude Code 会使用白名单允许的该族最新版本运行队友。在使用供应商特定模型 ID 的供应商上，此替换机制不起作用 (https://code.claude.com/docs/en/model-config#restrict-model-selection)，被屏蔽的别名会像下面一条中的其他被屏蔽值一样回退
• 任何其他被屏蔽的值，包括在替换机制不起作用的供应商上的族别名，或该族没有任何允许版本时：Claude Code 会改用主控的模型运行该队友。如果你设置了 CLAUDE_CODE_SUBAGENT_MODEL，Claude Code 会优先尝试该模型，同样遵循上述规则

默认情况下，队友继承主控的 effort level (https://code.claude.com/docs/en/model-config#adjust-effort-level)。在分屏窗格模式下，这一行为自 v2.1.186 起生效；更早的版本不会把主控会话的 effort 传递给分屏窗格中的队友。

让队友先规划再实现

对于复杂或高风险的任务，你可以让队友在实现之前先进行规划。当主控处于 plan mode (https://code.claude.com/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) 时，Claude 生成的队友会以只读的规划模式工作，直到其规划完成。先将主控切换到 plan mode，然后再要求生成队友：

当队友完成规划后，会向主控发送计划审批请求。Claude Code 会在请求到达时立即在主控会话中批准该计划，无需主控审阅。队友的编辑和命令仍需经过权限 (https://code.claude.com/docs/en/agent-teams#permissions) 中描述的权限确认流程。批准后，队友将退出规划模式，开始实现。

直接与队友对话

每个队友都是一个完整、独立的 Claude Code 会话。你可以直接向任何队友发送消息，下达额外指令、追问问题或调整其工作方向。

• 进程内模式：使用 agent 面板中的上下方向键选择队友，按 Enter 查看其会话并输入消息发送。按 x 可停止所选队友。按 Ctrl+T 切换任务列表的显示。
• 分屏窗格模式：点击某个队友的窗格即可与其会话直接交互。每个队友都拥有自己终端的完整视图。

当你在查看进程内队友时，普通文本和 skills (https://code.claude.com/docs/en/skills) 会发送给该队友，而内置命令会发送给主控会话，同时有以下保护措施：

• /compact、/clear 和 /rewind 作用于主控的对话，因此 Claude Code 会询问你确认后才从该视图中执行。
• /model 和 /fast 设置的是主控的模型和快速模式，而非队友的，因此无法从该视图中执行。会有一条提示说明原因。

队友的模型和快速模式在生成时即已固定。

分配与认领任务

共享任务列表用于协调全队的工作。主控创建任务，队友逐个完成。任务有三种状态：待处理（pending）、进行中（in progress）和已完成（completed）。任务也可以依赖其他任务：存在未完成依赖的待处理任务，在依赖完成之前无法被认领。不具备任务工具 (https://code.claude.com/docs/en/tools-reference#task-tool-availability) 的 agent 通过消息而非共享任务列表来协调。

主控可以显式分配任务，队友也可以自行认领：

• 主控分配：告诉主控把哪个任务交给哪个队友
• 自行认领：完成一个任务后，队友自行挑选下一个未分配且未被阻塞的任务

任务认领使用文件锁来防止多个队友同时尝试认领同一任务时产生竞态条件。

关闭队友

要优雅地结束一个……