Claude Code 深度学习手册

主题

Agent Teams（代理团队） ​

多个完整 Claude Code 会话协作：一个队长 + 多个队友，各自独立上下文、互相直接发消息、靠共享任务列表自协调（实验性）。

你的真实情况 ​

你还没启用 agent teams（需要环境变量），目前并行靠 subagent + 后台代理。要试团队：

json
// ~/.claude/settings.json
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

对你最对口的用法 ​

你常做前后端联调 + PR 评审 + 排错——这正是团队的强项场景：

  • 并行评审 SpringBlade 改动：「建团队，3 个队友：一个查鉴权/Tenant-Id、一个查 R<T> 响应包装、一个查 Nacos/启动配置，各自审完互相质疑再汇总」。
  • 竞争假设排错：登录 500 时，派几个队友各查一个理论（网关/token/租户头）并互相证伪。
  • 跨层：前端一人、SpringBlade 一人、联调一人，各管各的不踩脚。

比单个 pr-review-toolkit:code-reviewer 更全（队友能讨论），但 token 随队友数线性涨。官方建议 3–5 人。你装了 tmux 的话可开 split panes 一屏看全队。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

Agent teams（代理团队）让多个完整的 Claude Code 实例协作。一个会话当队长（lead）建队、派活、汇总；多个队友（teammate）各自独立上下文、互相直接发消息、靠共享任务列表自主认领任务。与 subagent 的本质区别：subagent 只能回报给主 agent、彼此不通信；团队队友互相通信、共享任务列表、自己认领——需要队友之间讨论/质疑/协调时才用团队。实验性功能，默认关闭。

怎么工作 ​

  • 架构 = 队长(lead) + 队友(teammates) + 共享任务列表(pending→in progress→completed，支持依赖与文件锁防抢) + 邮箱(mailbox，靠 SendMessage 通信)。
  • 你用自然语言让 Claude 建队并描述任务与角色；Claude 创建团队、spawn 队友、协调工作。
  • 每个队友是完整独立会话：自己的上下文窗口，加载项目的 CLAUDE.md/MCP/skills，但不继承队长的对话历史，只收到 spawn prompt。
  • 消息自动投递（无需轮询）；队友完成自动通知队长；可对单个队友直接发消息、指挥、要求其先出 plan 再实现。
  • 两种显示：in-process（Shift+Down 切换队友）或 split panes（每队友一个窗格，需 tmux 或 iTerm2）。
  • 完成后让队长 clean up 清理团队资源（队友还在跑时会失败，要先 shut down）。

怎么配置 / 用法 ​

启用（实验性，需 v2.1.32+）：

json
// settings.json
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

然后自然语言：『建一个团队，3 个队友分别从 UX / 架构 / 唱反调三个角度探索…』。

  • 显示模式：teammateMode（in-process / tmux / auto）或 claude --teammate-mode in-process。
  • 默认队友模型：/config 里 Default teammate model。
  • 可复用角色：spawn 时引用某个 subagent 类型（沿用其 tools/model，定义体作为附加指令）。
  • 质量门：TeammateIdle / TaskCreated / TaskCompleted 钩子。
  • 存储：团队配置 ~/.claude/teams/{team}/config.json，任务列表 ~/.claude/tasks/{team}/。

什么时候用 ​

  • 并行评审：安全/性能/测试各派一名，最后汇总。
  • 竞争假设并行调试：多名队友各查一个理论并互相证伪。
  • 新模块各管一块、跨前后端+测试的协调。
  • 官方建议先从研究/评审这类无需写码、边界清晰的任务上手；3–5 个队友、每人 5–6 个任务。
  • 别用：顺序任务、改同一文件、依赖多的活——单会话或 subagent 更划算。

限制 / 坑 ​

  • 实验性，默认关闭，需 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。
  • token 随队友数线性增长，比单会话贵得多。
  • 一次只能管一个团队；不能嵌套（队友不能再建队）；队长固定不可转让。
  • in-process 队友不支持 /resume、/rewind 恢复；任务状态有时滞后；关停较慢。
  • split panes 需 tmux 或 iTerm2，VS Code 集成终端 / Windows Terminal / Ghostty 不支持。

硬事实速查（7 条） ​

  • 启用开关：环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（需 Claude Code v2.1.32+）。
  • 通信工具 SendMessage；存储 ~/.claude/teams/{team}/config.json 与 ~/.claude/tasks/{team}/。
  • 组件：lead / teammates / 共享任务列表（依赖 + 文件锁）/ mailbox。
  • 显示模式 teammateMode：in-process / tmux / auto；split panes 需 tmux 或 iTerm2(it2 CLI)。
  • 官方建议 3–5 个队友、每人 5–6 个任务。
  • 和 subagent 区别：subagent 只回报主 agent、不互通；团队队友互相发消息、共享任务列表、自认领。
  • 限制：一次一个团队、不能嵌套、队长固定、权限在 spawn 时定。

官方出处：https://code.claude.com/docs/en/agent-teams