Agent 团队：多 Claude 实例协作与消息互通

从"派活"到"组队"

子代理是派活：主对话派一个专项工人，工人干完交报告，然后消失。Agent 团队是组队：多个 Claude 实例同时独立存在，各有各的上下文窗口，互相之间能直接发消息，还能共享一份任务清单，由一个 lead 协调全局。

先说清楚定位：这是实验性功能，默认关闭。启用方式：

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

打比方：子代理像你叫的外卖骑手，送到就走；Agent 团队像你拉了个项目群，几个人在里面互相讨论、认领任务、互相 challenge，最后给你交付。

什么时候值得组队

团队模式开销不小，先看它真正发光的四类场景：

• 多角度调研：设计评审找三个人分别从 UX、架构、反方视角研究，再互相碰撞；
• 独立新模块：前端、后端、测试各归一个队友，互不踩脚；
• 竞争性假设调试：三个队友并行验证三个 bug 假设，谁先找到算谁的；
• 跨层改动：一次改动横跨三层，各层独立推进。

反过来，串行任务、改同一批文件、依赖链长的活，老实用单会话或子代理。判断口诀：队友能独立运转就组队，需要频繁交接就别组。

从成本视角再补一刀：团队的 token 消耗是单会话的数倍，因为每个队友都是独立实例、每条互相之间的消息都要走模型。所以组队的性价比公式大致是"节省的日历时间 × 问题难度"对"数倍 token 成本"——对卡了很久的疑难问题前者巨大，对日常小任务前者趋零。这决定了团队模式的正确打开方式：当成攻克难题的重炮，而不是日常并行手段（日常并行请用上一章的 worktree）。

组你的第一个队

用自然语言描述任务和分工即可：

我在设计一个追踪代码库 TODO 的 CLI 工具。拉三个队友分别探索：
一个管 UX，一个管技术架构，一个专门唱反调。

Claude 会建共享任务清单、为每个视角生成队友、让他们各自探索，最后汇总结论。注意一点：Claude 有时自己决定用普通子代理而不是组队（面板上看着都像）——没组上就明确说"要一个 agent team"。

队友面板（lead 终端的提示框下方）操作：上下箭头选中队友，回车打开它的转录并直接给它发消息（可以越过 lead 直接指挥），Esc 清除选择、在查看转录时打断它当前动作。空闲队友的行 30 秒后收起，超过三个空闲的折叠成一行计数。

分屏模式：想让每个队友各占一块屏幕，需要 tmux 或 iTerm2。配置：

{ "teammateMode": "auto" }   // 或命令行 claude --teammate-mode auto

in-process（默认，全在主终端）→ auto（检测到 tmux/iTerm2 就分屏）→ tmux / iterm2（强制指定）。

模型与调度细节

队友用什么模型，按优先级取第一个生效的：你的生成提示里点名的 → 队友由子代理定义生成时定义里的 model → CLAUDE_CODE_SUBAGENT_MODEL 环境变量 → 沿用 lead 的模型。组织有 availableModels 白名单时被拦的值会自动替换（家族别名换成该家族最新可用版，其他情况退回 lead 的模型）。队友默认继承 lead 的推理力度（effort）。

还有个容易惊讶的联动行为：开着团队模式时，普通派遣也可能变成队友——Claude 给子代理起名字后，被点名的子代理会以队友身份启动，团队可能在你没点名要的情况下自然形成。只想让派遣保持子代理形态的话，可以关掉这个行为（官方文档有专门开关）。

消息互通的三层结构

多实例协作的信息流分三层，按需取用：

1. 队内消息：队友互相直接发消息讨论——这是团队模式独有的；你也能直接给任意队友发消息，不经过 lead；
2. 跨会话消息：不开团队也能让会话互相传话（cross-session messaging），worktree 并行时 A 会话的发现可以直接"告诉"B 会话；
3. 共享任务清单：有 Task 工具的队友共享同一份清单，认领、流转都在上面，Ctrl+T 可查看 Claude 的任务清单。

用子代理定义当队友模板

一个提效技巧：队友可以复用子代理定义。把第 3 节讲的 .claude/agents/ 里的定义指给 lead——"按 debugger 这个子代理的定义拉一个队友"，Claude Code 会把定义里的提示词、工具限制等应用到队友身上，定义里的 model: inherit 则沿用 lead 的模型。这让"子代理库"升级成了"队员花名册"：同一个定义既能当临时工人（子代理），也能当长期队员（队友）。

生成队友时还可以直接指定显示模式、模型和职责分工，一句话把队伍章程说全：

拉一个四人团队重构 src/legacy/：一个负责拆 services，一个负责迁移
路由，一个写测试，一个做 review。都用 Sonnet，分屏显示。

与 worktree 并行的关系

团队模式和并行会话解决的是不同维度的问题，但在大项目里会相遇。并行会话（上一章）是你同时推进多个任务，每个会话独立、互不知晓；团队模式是一个任务内部的多角色协作，队友之间高频互通。判断用哪个的问题不是"哪个更高级"，而是"通信发生在哪"：任务之间没有信息交换需求就并行会话，任务内部需要协作讨论就组队。两者也能叠——不过对多数团队规模来说，叠用属于炫技而非必要。

组队的工作流细节

实际带一次队，你会碰到这些操作点，提前列清楚：

• 查看与接管：lead 面板里回车进队友转录，直接打字就是对它说话——指挥权和 lead 并行，你随时可以越过 lead 给某个队友补上下文或改方向；
• 打断：查看某队友转录时按 Esc 打断它的当前动作；Ctrl+X Ctrl+K（3 秒内按两次）停掉本会话所有后台代理；
• 任务清单：共享清单是团队的"白板"，队友认领、推进、完成都在上面流转，你用 Ctrl+T 随时看进度；
• 收尾：所有队友空闲后 lead 汇总，面板行 30 秒后收起但队友仍可寻址——想加活直接在面板选中再发。

组队前还要确认环境前提：交互式会话（-p 里不生成队友）、环境变量已开、tmux/iTerm2 用户装好分屏依赖。lead 的系统提示里会带团队协作指令，所以给 lead 的任务描述最好包含"何时算完成"的验收口径——lead 会把它传给队友，减少各自理解的漂移。

实战心得与限制

带队半年下来的心得：lead 的指令质量决定团队上限。lead 是你唯一直接对话的入口（虽然可以越级），给它的任务分解和约束越清楚，整个队的产出越稳定；甩一句"把这个项目重构了"进团队，收获的是昂贵而混乱的自由发挥。

一个真实案例：竞争性调试

用我印象最深的一次实战收尾：一个"偶发的订单金额计算错误"，单人排查两天无果。组了三人队并行验证三个假设：

@lead 假设这个问题出在并发场景。拉三个队友分别验证：
队友A：怀疑定时任务和手动操作竞态，找证据
队友B：怀疑浮点累加精度，复现最小用例
队友C：怀疑多币种汇率换算的时序，查调用链
每人用 worktree 隔离，发现可复现路径立即向 lead 汇报并互相同步

四十分钟后队友 B 报告：用 0.1 加三次再乘 1000 能稳定复现——浮点精度假设命中。队友 A、C 的排查过程虽然没直接命中，但它们顺手排除了两个方向，并在讨论中补充了边界条件。整个团队消耗大约是单人排查三倍的 token，但省下的是两天日历时间。这个账在"卡了很久的疑难问题"上是划算的，在日常任务上不划算——再次强调团队模式的使用场合。

已知限制要心里有数（实验性功能的代价）：会话恢复、任务协调、关闭行为都还有边角问题，官方文档的 limitations 一节值得开队前读一遍。-p 无头模式里不会生成队友——被点名的子代理仍按普通子代理跑。token 消耗是单会话的数倍，团队模式放在预算里的正确位置是"偶尔为之的重炮"，不是"日常默认"。

完整能力与最新变化见官方 Agent 团队文档。下两章讲无头模式——不组队但要把 Claude 塞进流水线时的正解。

本章由 WorkBuddy 原创整理，事实性内容参考 Claude Code 官方文档。