08 · 多个 AI 怎么协作

翔宇第一次把前端、后端、测试分别交给三个 SubAgents（子代理）时，以为这就是“多 AI 协作”。结果后端把字段从 userName 改成 name，前端还在用旧字段，测试也不知道什么时候能开始。问题不在于 AI 不够多，而在于它们各干各的，没有共享任务列表，也没有消息系统。——翔宇

1. 从一次前后端返工开始

先看一个具体场景。

你让 Claude Code 做一个登录功能。任务看起来很适合拆开：

• 后端：实现登录、注册、刷新 token。
• 前端：实现登录页和注册页。
• 测试：等前后端完成后写集成测试。

如果用第 7 篇的 SubAgents，你可能会这样安排：

派一个 subagent 写后端
派一个 subagent 写前端
派一个 subagent 准备测试

表面上很合理。三个任务并行，速度应该变快。

但很快会出问题。

后端开发到一半，把响应字段从 userName 改成 name。前端那个 subagent 不知道，因为它只和主对话汇报，不会主动和后端 subagent 通信。测试那个 subagent 也不知道前后端什么时候都完成，只能等主对话转告。

你本来想当负责人，结果变成传话筒：

前端问你：后端字段叫什么？
你去问后端。
后端告诉你：叫 name。
你再转告前端。
测试问你：我能开始了吗？
你再去确认前端和后端。

这不是团队协作，这是你在替三个房间里的人传纸条。

如果任务之间没有依赖，也不需要互相对齐，SubAgents 就够了。如果任务之间会互相影响，光把它们分出去不够。

2. SubAgents 缺的不是人，是协作层

第 7 篇说过，SubAgent 的结构是主从关系。

flowchart LR
    Main["主对话"]
    A["SubAgent A<br/>后端"]
    B["SubAgent B<br/>前端"]
    C["SubAgent C<br/>测试"]
    RA["摘要 A"]
    RB["摘要 B"]
    RC["摘要 C"]

    Main --> A
    Main --> B
    Main --> C
    A --> RA --> Main
    B --> RB --> Main
    C --> RC --> Main

    style Main fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style A fill:#dcfce7,stroke:#22c55e
    style B fill:#dcfce7,stroke:#22c55e
    style C fill:#dcfce7,stroke:#22c55e

这个结构很适合“分别查三个模块，最后给我摘要”。

但它不适合“后端字段会影响前端，前端完成会影响测试”。因为 SubAgents 之间没有共同白板，也没有直接讨论。

Agent Teams 多出来的正是协作层：

flowchart TB
    Lead["Team Lead<br/>主 Claude Code 会话"]
    Board["Shared task list<br/>共享任务列表"]
    Mail["Mailbox<br/>成员消息系统"]
    Backend["Teammate<br/>backend-dev"]
    Frontend["Teammate<br/>frontend-dev"]
    Test["Teammate<br/>test-dev"]

    Lead --> Board
    Lead --> Backend
    Lead --> Frontend
    Lead --> Test
    Backend <--> Mail
    Frontend <--> Mail
    Test <--> Mail
    Backend --> Board
    Frontend --> Board
    Test --> Board

    style Board fill:#f3e8ff,stroke:#a855f7,stroke-width:2px
    style Mail fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Lead fill:#dbeafe,stroke:#3b82f6,stroke-width:2px

官方文档说，Agent Teams 用多个 Claude Code instances（独立会话）协作，有 shared tasks、inter-agent messaging 和 centralized management。也就是说，它不是“更多 SubAgents”，而是“多会话 + 共享任务 + 成员消息 + lead 管理”。

3. 共享任务列表解决什么

先只看 shared task list。

在登录功能里，你可以把任务拆成：

这张表的意义不是“看起来有管理感”，而是让团队成员知道全局状态。

后端完成后，把后端登录 API 标为 completed（已完成）。前端完成后，也标为 completed。测试任务看到两个依赖都满足，就从 blocked（被阻塞）变成可以领取。

你不用反复问：

后端做完了吗？
前端做完了吗？
测试能开始了吗？
谁现在空着？

任务列表本身就回答了这些问题。

官方文档里也明确写到：shared task list 会协调工作，任务有 pending、in progress、completed 三种状态，也可以有依赖；依赖完成后，被阻塞的任务会自动解除阻塞。

任务状态机怎么实现：shared task list 不是模型推理出来的——它是 Claude Code runtime 维护的真实数据结构（写在 ~/.claude/tasks/{team-name}/）。每个 teammate 通过工具调用读 / 改任务状态：把任务从 pending 标 in_progress 是显式动作（不是模型"想到了"），完成时显式 mark completed 触发依赖解除。为什么这样设计：如果状态靠模型每轮推理，5 个 teammate 各自的"以为"会冲突（A 以为 B 没做完，B 以为 A 已经看了）；落到 runtime 就是单一真相源，不会出现"两个 teammate 都觉得自己负责" 的协作崩溃。

这里还有一个容易忽略的点：共享任务列表不是“让 AI 自由发挥”的理由。任务越清楚，团队越稳。

坏任务：

做完登录功能。

好任务：

先定下登录接口的响应字段约定（auth response schema）。
schema 经评审后，开始实现后端登录接口。
schema 经评审后，开始搭建前端登录与注册页。
后端和前端都完成后，再写集成测试。

前者会让每个 teammate 自己猜边界。后者把依赖关系提前写出来，团队才知道哪些事能并行，哪些事必须等。

4. 消息系统解决什么

有任务列表还不够。

任务列表告诉大家“状态是什么”，但不能替代讨论。

前端做到一半发现接口问题：

frontend-dev -> backend-dev:
登录接口现在返回 name 还是 userName？错误码字段叫 code 还是 errorCode？

后端直接回复：

backend-dev -> frontend-dev:
统一用 name；错误码字段叫 code。schema 我已经在 auth contract 里更新。

这条消息不需要通过你转发。

官方文档说，teammate messages 会自动送达，不需要 lead 轮询；每个 teammate 都有名字，可以按名字直接发消息。要联系所有人，不是"广播一个神秘频道"，而是给每个接收者发送消息。

mailbox 怎么"自动送达"：每个 teammate 是独立的 Claude Code 进程，runtime 维护一个共享 mailbox（实现细节是文件 / IPC，对用户透明）。teammate A 给 B 发消息——runtime 把消息追加到 B 的下一轮 user message 前，B 在下一次响应时就能看到。所以"自动送达"不等于"实时"——B 必须在等待输入或刚完成上一轮时才能"收到"。如果 B 正在长任务中（比如跑测试 30 秒），消息要等它本轮结束才进上下文。这是为什么 §6 强调"任务粒度要小"——大任务里 teammate 听不到对方提醒。

这有一个很现实的好处：你可以给成员起可预测的名字。

为登录功能开一个 agent team。
把队友命名为 backend-dev、frontend-dev、test-dev。

后续你就能明确说：

让 frontend-dev 在动 UI 代码之前，先和 backend-dev 确认登录接口的字段名。

5. 一个真实工作流长什么样

把登录功能完整走一遍。

第一步：让 lead 建队

你不需要手写团队配置文件。直接用自然语言说清任务和角色：

为登录功能开一个 agent team。

设三个队友：
- backend-dev 负责登录、注册、刷新 token 三个接口。
- frontend-dev 负责登录页和注册页。
- test-dev 负责集成测试。

要求 backend-dev 和 frontend-dev 在 test-dev 开始之前，先就响应字段约定达成一致。
避免成员改同一个文件。

官方文档说，你请求团队时，Claude 会创建团队、spawn teammates（启动队友）并协调工作。Claude 也可能建议创建团队，但不会不经你同意就创建。

这里有三句很值得加：

每个队友动手改文件之前，先报上自己的计划。
只批准能保持文件归属互不重叠的计划。
等所有队友完成后，lead 再开始动手实现。

这三句分别解决三个常见问题：先计划，避免上来就改；分文件，避免互相覆盖；让 lead 真正做协调者，不要成员还没回来，lead 自己先下场写一半。

第二步：任务板开始工作

lead 把任务拆成可领取项：

schema 先稳定，后端和前端再并行。这样不是“越并行越好”，而是先把会影响所有人的契约定住。

第三步：成员直接对齐

frontend-dev 不确定字段名时，直接问 backend-dev。backend-dev 修改接口后，也直接通知 frontend-dev。

你可以随时插手：

告诉 frontend-dev 把 UI 保持在最小可用版本，不要重新设计整个登录流程。

第四步：收尾和清理

任务完成后，不是让所有 teammate 无限挂着。官方文档建议通过 lead 关停成员并清理团队资源：

让所有队友先关停，再清理整个 team。

团队配置和任务列表会存到本机：

~/.claude/teams/{team-name}/config.json
~/.claude/tasks/{team-name}/

这些是运行状态文件，不要手工预写或长期维护。需要复用角色时，应该写 SubAgent definition，而不是编辑 team config。

6. 什么时候值得开团队

Agent Teams 成本比 SubAgents 高很多。每个 teammate 都是独立 Claude Code 会话，token 用量会随活跃 teammate 增长。

所以判断标准要严一点。

官方给的强场景包括 research and review、new modules or features、debugging with competing hypotheses、cross-layer coordination。弱场景是顺序任务、同文件编辑、依赖太多的任务。

还有一个实操判断：如果你说不出每个 teammate 的独立交付物，就先不要开团队。

backend-dev -> auth API diff + schema note
frontend-dev -> login/register UI diff
test-dev -> integration test file + failing/passing result

能说成这样，团队才有清楚的边界。说不清，只会变成几个 Claude 在同一个代码库里同时摸索，冲突和成本都会上来。

三个应该停下来的信号

新手最常见的两类失败开团方式：

1. 任务边界没切清就开团：直接说"开个 team 帮我做完登录功能"——没指定每个 teammate 的文件归属，结果两个 teammate 都改 auth.ts，最后合并冲突或互相覆盖。修复：开团前先列每个 teammate 的"owned files + 不许碰的文件"，让 lead 把这个写进任务说明。
2. lead 自己下场代替协调：开了 3 个 teammate 但 lead 等不及，自己开始写代码——结果 lead 的进展跟 teammates 的进展互相不知道，最后 4 套并行的修改合不起来。修复：lead 角色就是"分任务 + 看 mailbox + 仲裁 + 汇总"，不实现具体功能。

开团队后，如果出现下面三种情况，要立刻收束，而不是继续加 teammate：

Agent Teams 最怕“看起来很热闹”。终端里多个 Claude 同时滚动，不代表任务推进更稳。真正值得保留的团队，应该让你更少传话、更少重复解释、更容易看到谁被什么阻塞。

7. 怎么打开和怎么看

Agent Teams 是实验性功能，默认关闭。官方要求 Claude Code v2.1.32 或更新版本，可以先检查：

claude --version

启用方式是设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

也可以写进设置：

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

显示模式主要有两种：

默认是 auto：如果你已经在 tmux 里，就倾向 split panes；否则用 in-process。也可以在 ~/.claude/settings.json 里指定：

{
  "teammateMode": "in-process"
}

8. 三个安全边界

Agent Teams 真正难的不是启动，而是控制风险。

边界一：文件所有权

两个 teammate 同时改同一个文件，很容易互相覆盖。

启动前就要写清：

backend-dev 负责 src/server/auth/** 下所有文件。
frontend-dev 负责 src/app/login/** 和 src/app/register/** 下所有文件。
test-dev 负责 tests/auth/** 下所有文件。
不在自己负责范围之外动任何文件，需要时先跟 lead 确认。

这比事后处理冲突强得多。

边界二：权限继承

官方文档说，teammates 会从 lead 继承权限设置。如果 lead 用了危险的跳过权限模式，teammates 也会继承。

所以不要在没想清楚时用高权限 lead 开团队。团队不是一个 AI 在动手，而是多个会话同时动手。

边界三：不要放任太久

官方建议要 monitor and steer（监控并引导）。团队能自协调，不等于你可以去睡觉。

尤其是实现类任务，最好要求：

• 先研究和计划。
• 高风险改动前等 lead 确认。
• 每个 teammate 只负责一小块可交付结果。
• 完成后让 lead 汇总 diff、风险和测试结果。

启动前可以把这段当成最小护栏：

每个队友动手之前，必须说明：
- 自己负责哪些文件
- 计划要做什么改动
- 预期会跑哪些测试
- 如果其它队友动相关文件，会有什么风险

lead 必须拒绝那些会覆盖到同一文件的计划，除非已经显式批准。

这不是为了把 prompt 写复杂，而是为了把“冲突”提前暴露出来。多会话协作里，最贵的不是多花几千 token，而是三个会话各自做对了一部分，最后合不起来。

9. 和 SubAgent definition 的关系

第 7 篇讲过，自定义 SubAgent 可以写在 .claude/agents/ 或 ~/.claude/agents/。

Agent Teams 可以复用这些 definition。比如你已经有一个 security-reviewer，可以这样说：

用 security-reviewer 这个 agent 类型派一个队友，让它审计 auth 模块。

官方文档说明：teammate 会尊重这个 definition 里的 tools allowlist 和 model，正文会作为额外指令附加到 teammate 的系统提示里。

但有一个细节要记住：当 subagent definition 被当作 teammate 使用时，里面的 skills 和 mcpServers frontmatter 不会按 subagent 方式应用。teammates 会像普通会话一样从项目和用户设置加载 skills 与 MCP servers。

这句话听起来细，但能避免一个坑：不要以为“我在 subagent definition 里给它配了某个 MCP，作为 teammate 时也一定生效”。团队场景下要按团队文档的规则来。

10. 本章自检

试着用自己的话回答：

1. 有人说"Agent Teams 就是更多 SubAgents"。这个说法少了哪两个机制？对应 §2。
2. 为什么前端、后端、测试这种跨层任务适合 Agent Teams，而查三个模块更适合 SubAgents？对应 §3-§6。
3. 动手题 ⭐：拿你最近一次的"多模块任务"（比如加一个新功能要同时改前端 / 后端 / 测试）。判断：当时该单人主对话做、派 SubAgent、还是开 Agent Teams？写下你的理由。三个判断维度：① 任务之间有没有跨层依赖？② 过程产出会不会污染主对话？③ 多角色之间需不需要互相对齐？三个全是"是"才开 Teams——不是"是"就先 SubAgent 或主对话。对应 §6 + §8。

官方资料

• Create custom subagents
• Agent SDK overview

接下来去哪

如果只记一个判断：SubAgents 是“派人查完回来汇报”，Agent Teams 是“组队共用任务板和消息系统一起推进”。