---
title: "08 · 多个 AI 怎么协作"
description: "Agent Teams 不是更多 SubAgents，而是让多个 Claude Code 会话带着共享任务列表和消息系统协作，适合跨模块、多假设、需要对齐的任务。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

> [!NOTE]
> **这一篇用 16 分钟换什么**：第 7 篇讲了 SubAgents 适合“只要结论”的旁支任务。这一篇讲 Agent Teams（代理团队）：什么时候 SubAgents 不够，为什么需要 shared task list（共享任务列表）和 mailbox（消息系统），以及为什么它默认关闭、不能随便上生产任务。

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

先看一个具体场景。

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

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

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

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

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

但很快会出问题。

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

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

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

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

> [!IMPORTANT]
> **第一性原理**：Agent Teams 解决的不是“派更多 AI”，而是“多个 AI 之间需要共享状态和互相通信”。

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

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

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

```mermaid
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 多出来的正是协作层：

```mermaid
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 管理”。

> [!TIP]
> **一句话理解**：SubAgents 像你派人出去查资料，查完回报；Agent Teams 像你开了一个项目组，大家看同一块任务板，还能互相发消息。

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

先只看 shared task list。

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

| 任务 | 状态 | 依赖 | 负责人 |
|------|------|------|------|
| 后端登录 API | `in_progress` | 无 | `backend-dev` |
| 前端登录页 | `in_progress` | 后端接口字段稳定 | `frontend-dev` |
| 集成测试 | `pending` | 后端 API + 前端页面 | 未领取 |

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

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

你不用反复问：

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

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

官方文档里也明确写到：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 都觉得自己负责" 的协作崩溃。

> [!IMPORTANT]
> **底层逻辑**：共享任务列表把“谁在做什么、什么能开始、什么被阻塞”从主对话脑子里搬到公共状态里。没有它，你仍然是人工调度员。

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

坏任务：

```text
做完登录功能。
```

好任务：

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

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

## 4. 消息系统解决什么

有任务列表还不够。

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

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

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

后端直接回复：

```text
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 听不到对方提醒。

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

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

后续你就能明确说：

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

> [!WARNING]
> **新手坑**：不要给 teammate 起含糊名字，比如 `agent1`、`helper`、`worker`。名字越清楚，后续消息越少出错。

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

把登录功能完整走一遍。

### 第一步：让 lead 建队

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

```text
为登录功能开一个 agent team。

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

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

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

这里有三句很值得加：

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

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

### 第二步：任务板开始工作

lead 把任务拆成可领取项：

| 任务 | 状态 | 依赖 |
|------|------|------|
| Define auth response schema | `in_progress` | 无 |
| Implement backend auth API | `pending` | schema |
| Build frontend auth pages | `pending` | schema |
| Write integration tests | `pending` | backend + frontend |

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

### 第三步：成员直接对齐

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

你可以随时插手：

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

### 第四步：收尾和清理

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

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

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

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

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

## 6. 什么时候值得开团队

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

所以判断标准要严一点。

| 场景 | 推荐 | 原因 |
|------|------|------|
| 查认证、数据库、API 三个互不依赖模块 | SubAgents | 只要摘要，不需要互相通信 |
| 前端、后端、测试要同时改并对齐契约 | Agent Teams | 有跨层依赖和消息需求 |
| 安全、性能、测试覆盖三种视角审查同一个 PR | Agent Teams | 多视角互相补充，lead 汇总 |
| 一个小 bug、一处变量名、一段报错解释 | 主对话 | 团队开销大于收益 |
| 多人要改同一个文件 | 主对话或谨慎拆分 | Agent Teams 容易文件冲突 |

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

> [!TIP]
> **决策句**：需要互相通信和共享任务状态，才上 Agent Teams；只是隔离噪音和拿摘要，用 SubAgents；单步任务留在主对话。

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

```text
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：

| 信号 | 说明 | 更稳做法 |
|------|------|------|
| 每个成员都在问同一个背景问题 | spawn prompt 信息不够 | 暂停，补一份统一任务说明 |
| 两个成员开始改同一个文件 | 文件所有权没拆清 | 停止其中一个，重新分工 |
| lead 频繁亲自下场实现 | 团队没有清楚交付物 | 让 lead 回到协调和汇总 |

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

## 7. 怎么打开和怎么看

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

```bash
claude --version
```

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

```bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```

也可以写进设置：

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

显示模式主要有两种：

| 模式 | 怎么看 | 适合谁 |
|------|------|------|
| in-process | 所有 teammate 在主终端里，`Shift+Down` 切换 | 不想配 tmux 的新手 |
| split panes | 每个 teammate 一个窗格，可同时看输出 | 熟悉 tmux 或 iTerm2 的用户 |

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

```json
{
  "teammateMode": "in-process"
}
```

> [!CAUTION]
> **不要手敲错**：环境变量必须完整写成 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`，大小写也要一致。复制官方写法，比凭记忆输入更稳。

## 8. 三个安全边界

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

### 边界一：文件所有权

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

启动前就要写清：

```text
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、风险和测试结果。

> [!IMPORTANT]
> **底层逻辑**：Agent Teams 放大的是协作能力，也会放大权限、成本和文件冲突。越多人同时动手，边界越要提前写清。

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

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

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

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

## 9. 和 SubAgent definition 的关系

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

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

```text
用 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 时也一定生效”。团队场景下要按团队文档的规则来。

<details>
<summary><b>🔍 深一层：为什么 team config 不该手工编辑</b></summary>

Agent Teams 的运行状态会写在 `~/.claude/teams/{team-name}/config.json`。里面有成员名、agent ID、session ID、tmux pane ID 等运行时信息。

这不是你该维护的项目配置。Claude Code 会在团队创建、成员加入、成员空闲、成员退出时自动更新它。你手工写的内容可能在下一次状态更新时被覆盖。

想复用角色，写 SubAgent definition。想复用工作方式，写 prompt 或 Skill。不要把 team config 当模板仓库。

</details>

## 10. 本章自检

试着用自己的话回答：

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

> [!TIP]
> **过关标准**：能用一句话说清：Agent Teams 适合需要共享任务状态和成员通信的多会话协作；不需要协作层的任务，不该硬开团队。

<details id="glossary">
<summary><b>本篇术语速查表</b></summary>

- **Agent Teams**：代理团队，多个 Claude Code 会话围绕同一任务协作。
- **teammate**：队友会话，团队里独立工作的 Claude Code 实例。
- **team lead**：团队负责人，创建团队、分配任务、汇总结论的主会话。
- **shared task list**：共享任务列表，所有成员都能看到和更新的任务状态。
- **mailbox**：消息系统，teammate 之间直接传递信息的机制。
- **dependency**：依赖，某个任务开始前必须完成的前置任务。
- **teammateMode**：队友显示模式，控制 in-process 或 split panes 展示方式。
- **tmux**：终端复用工具，用多个 pane 同时显示 teammate 输出。
- **SubAgent definition**：子代理定义，可复用的 agent 角色文件，可被 teammate 引用。

</details>

## 官方资料

- [Create custom subagents](https://code.claude.com/docs/en/sub-agents)
- [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview)

## 接下来去哪

<Cards>
  <Card href="/docs/claude-code/understanding/09-mcp" title="➡️ 09 · 怎么连外部服务" description="团队和子代理解决的是人手与协作。下一篇讲 MCP：Claude Code 怎么接外部工具、数据源和服务。" />
  <Card href="/docs/claude-code/understanding/07-subagents" title="07 · 派助手去干活（上一篇）" description="复习 SubAgents：它只回摘要，不互相协作。理解这个边界，第 8 篇才不容易用重。" />
  <Card href="/docs/claude-code/understanding/11-permissions" title="11 · 权限怎么管" description="Agent Teams 会放大权限影响。做多会话协作前，最好先理解权限和审批边界。" />
</Cards>

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