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 是“組隊共用任務板和訊息系統一起推進”。