协调 Claude Code 会话团队

​

何时使用 agent teams

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

​

与 subagents 比较

​

启用 agent teams

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

​

启动你的第一个 agent team

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

• 向上和向下箭头：选择一个队友
• Enter：打开所选队友的记录并直接向其发送消息
• Escape：清除选择。当你正在查看队友的记录时，Escape 会中断该队友的当前轮次

​

控制你的 agent team

​

选择显示模式

• In-process：所有队友在你的主终端内运行。在 agent 面板中使用上下箭头键选择队友，然后按 Enter 查看它并输入以直接向它发送消息。在任何终端中工作，无需额外设置。
• Split panes：每个队友获得自己的窗格。你可以同时看到每个人的输出，并点击窗格直接交互。需要 tmux 或 iTerm2。

{
  "teammateMode": "auto"
}

claude --teammate-mode auto

• tmux：通过你的系统包管理器安装。有关特定于平台的说明，请参阅 tmux wiki。
• iTerm2：安装 it2 CLI，然后在 iTerm2 → Settings → General → Magic → Enable Python API 中启用 Python API。

​

指定队友和模型

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

1. 你的生成提示为该队友命名的模型。
2. 对于从子 agent 定义生成的队友，定义的 model，其中 inherit 选择负责人的模型。
3. CLAUDE_CODE_SUBAGENT_MODEL，当它设置为除 inherit 之外的任何值时。
4. 负责人的当前模型。

• 系列别名如 opus：在 Anthropic API 和 AWS 上的 Claude Platform 上，Claude Code 在允许列表允许的该系列的最新版本上运行队友。在具有特定于提供商的模型 ID 的提供商上，其中替换不起作用，被阻止的别名会根据下一个项目符号回退，如同任何其他被阻止的值一样
• 任何其他被阻止的值，包括在替换不起作用的提供商上的系列别名，或其系列没有允许版本的别名：Claude Code 在负责人的模型上运行队友。如果你设置 CLAUDE_CODE_SUBAGENT_MODEL，Claude Code 首先尝试该模型，遵循相同的规则

​

让队友在实施前进行规划

Spawn an architect teammate to refactor the authentication module.

​

直接与队友交谈

• In-process 模式：在 agent 面板中使用上下箭头键选择队友，然后按 Enter 查看其会话并输入以向其发送消息。在选定的队友上按 x 以停止它。按 Ctrl+T 切换任务列表。
• Split-pane 模式：点击队友的窗格以直接与他们的会话交互。每个队友都有自己终端的完整视图。

​

分配和认领任务

• 负责人分配：告诉负责人将哪个任务分配给哪个队友
• 自我认领：完成任务后，队友自己选择下一个未分配、未阻止的任务

​

关闭队友

Ask the researcher teammate to shut down

​

使用 hooks 强制质量门

• TeammateIdle：当队友即将空闲时运行。以代码 2 退出以发送反馈并保持队友工作。
• TaskCreated：当任务被创建时运行。以代码 2 退出以防止创建并发送反馈。
• TaskCompleted：当任务被标记为完成时运行。以代码 2 退出以防止完成并发送反馈。

​

Agent teams 如何工作

​

Claude 如何启动 agent teams

​

架构

• Team config：~/.claude/teams/{team-name}/config.json
• Task list：~/.claude/tasks/{team-name}/

​

为队友使用 subagent 定义

Spawn a teammate using the security-reviewer agent type to audit the auth module.

• tools：Claude Code 将队友限制为定义的 tools 列表中的工具。对于进程内队友，Claude Code 将 SendMessage 添加到该列表，在 具有 Task tools 的会话 中，它还添加 TaskCreate、TaskGet、TaskList 和 TaskUpdate。
• model：当你的生成提示没有命名模型时，Claude Code 在任一显示模式中使用定义的 model。请参阅 Claude Code 如何选择队友的模型。
• Body：对于进程内队友，Claude Code 将定义的主体附加到其默认系统提示作为额外指示。对于分割窗格队友，Claude Code 使用主体代替其默认系统提示。
• skills：Claude Code 在任一显示模式中都不将定义的 skills 应用于队友。队友从你的项目和用户设置加载 skills。
• mcpServers：对于分割窗格队友，Claude Code 在 该字段的规则 下应用定义的 mcpServers，这些规则涵盖使用 --agent 启动的会话。进程内队友忽略该字段，从你的项目和用户设置加载 MCP servers。

​

权限

​

代理之间的消息

• 它将从另一个代理转发的批准声明视为不受信任的输入，而不是来自你的确认。
• 它在 Claude Code 传递消息之前审查每条消息，无论是纯消息还是结构化协议消息（如关闭请求或计划批准响应）。它阻止的消息永远不会到达收件人。

​

Context 和通信

• 自动消息传递：当队友发送消息时，它们会自动传递给收件人。负责人不需要轮询更新。
• 空闲通知：当队友完成并停止时，它会自动通知负责人并在通知中包含其最终答案。其轮次因 API 错误而结束的队友会通知负责人它失败了并包含错误文本。
• 共享任务列表：具有 Task tools 的代理 可以看到任务状态并认领可用工作。
• 队友消息传递：按名称向一个特定的队友发送消息。要联系所有人，请为每个收件人发送一条消息。

​

令牌使用

​

用例示例

​

运行并行代码审查

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

​

使用竞争假设进行调查

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.

​

最佳实践

​

给队友足够的 context

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

​

选择适当的团队规模

• 令牌成本线性增加：每个队友都有自己的 context window 并独立消耗令牌。有关详细信息，请参阅 agent team 令牌成本。
• 协调开销增加：更多队友意味着更多通信、任务协调和潜在冲突
• 收益递减：超过一定点，额外的队友不会按比例加快工作

​

适当调整任务大小

• 太小：协调开销超过收益
• 太大：队友长时间工作而不进行检查，增加浪费努力的风险
• 恰到好处：自包含的单位，产生清晰的可交付成果，例如函数、测试文件或审查

​

等待队友完成

Wait for your teammates to complete their tasks before proceeding

​

从研究和审查开始

​

避免文件冲突

​

监控和指导

​

故障排除

​

队友未出现

• 在 in-process 模式中，队友出现在提示输入下方的代理面板中。使用上下箭头键选择一个，然后按 Enter 键查看它。
• 闲置后消失的队友行已被隐藏，而不是停止。闲置行在整个面板闲置 30 秒后隐藏，并在队友的下一轮出现时重新出现。当超过三个队友闲置时，他们的多余行会折叠成一个 N idle agents 行，按 Enter 键可展开。按名称向队友发送消息以将隐藏的行恢复。
• 检查你给 Claude 的任务是否足够复杂以保证需要团队。Claude 根据任务决定是否生成队友。
• 如果你明确要求分割窗格，请确保 tmux 已安装并在你的 PATH 中可用：
  which tmux
  
• 对于 iTerm2，验证 it2 CLI 已安装，并在 iTerm2 偏好设置中启用了 Python API。

​

Claude 生成队友而不是子代理

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

• 更高优先级的设置文件：项目设置、本地设置和 --settings 有效负载在用户设置之后应用，所以在其中任何一个中将变量设置为 1 的 env 条目会获胜。请参阅 设置优先级。
• 托管设置：托管设置 在所有其他源之后应用。如果你的组织在那里启用了代理团队，请要求你的管理员更改托管值。

​

过多权限提示

​

代理提前停止

• 直接给他们额外的指示
• 生成一个替代队友来继续工作

​

孤立的 tmux 会话

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

​

限制

• In-process 队友没有会话恢复：/resume 和 /rewind 不会恢复 in-process 队友。恢复会话后，负责人可能会尝试向不再存在的队友发送消息。如果发生这种情况，告诉负责人生成新队友。
• 任务状态可能滞后：队友有时无法将任务标记为已完成，这会阻止依赖任务。如果任务似乎卡住，检查工作是否实际完成，并手动更新任务状态或告诉负责人推动队友。
• 关闭可能很慢：队友在关闭前完成他们的当前请求或工具调用，这可能需要时间。
• 每个会话一个团队：一个会话恰好有一个团队，作用域限于该会话。你无法创建额外的命名团队或在会话间共享团队。
• 没有嵌套团队：队友无法生成自己的队友。只有负责人可以管理团队。
• 没有来自 in-process 队友的后台子代理：in-process 队友自己的子代理在前台运行，因为队友的后台工作无法超越负责人的进程。Claude Code 在队友生成定义设置 background: true 的子代理时返回错误。队友的 run_in_background: true 请求也会失败，要么返回错误，要么如 Claude Code 如何选择前台或后台 中所述在前台静默运行。从主对话启动的子代理遵循后台默认值。
• 负责人是固定的：主会话在其生命周期内是其团队的负责人。你无法将队友提升为负责人或转移领导权。
• 权限在生成时设置：队友从 权限 下描述的权限模式开始。你可以在生成后更改个别队友的权限模式，但在生成时无法设置每个队友的权限模式。
• 分割窗格需要 tmux 或 iTerm2：默认 in-process 模式在任何终端中工作。VS Code 的集成终端、Windows Terminal 或 Ghostty 不支持分割窗格模式。

​

后续步骤

• 轻量级委派：subagents 在你的会话中生成辅助代理以进行研究或验证，更适合不需要代理间协调的任务
• 在你自己的会话之间进行消息传递：cross-session messaging 让 Claude 在你自己运行的会话之间传递发现
• 手动并行会话：Git worktrees 让你自己运行多个 Claude Code 会话，无需自动化团队协调