---
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="/zh-Hant/docs/claude-code/understanding/09-mcp" title="➡️ 09 · 怎麼連外部服務" description="團隊和子代理解決的是人手與協作。下一篇講 MCP：Claude Code 怎麼接外部工具、資料來源和服務。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/07-subagents" title="07 · 派助手去幹活（上一篇）" description="複習 SubAgents：它只回摘要，不互相協作。理解這個邊界，第 8 篇才不容易用重。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/11-permissions" title="11 · 許可權怎麼管" description="Agent Teams 會放大許可權影響。做多會話協作前，最好先理解許可權和審批邊界。" />
</Cards>

如果只記一個判斷：**SubAgents 是“派人查完回來彙報”，Agent Teams 是“組隊共用任務板和訊息系統一起推進”。**
