Claude Code Agent Teams：多 Agent 協作的新境界

前置閱讀建議

本文介紹 Claude Code 的實驗性 Agent Teams 功能。如果你還不熟悉 Subagents 的基本概念，建議先閱讀以下文章：

• 如何有效使用 Claude Code 子 Agents
• Claude Code Subagents 與 Plan Mode：智能協作新紀元

你有沒有遇過這樣的場景？一個大型重構任務，你需要同時分析安全性、效能影響和測試覆蓋率 — 但一個 Agent 一次只能專注一件事。Subagents 雖然能分工，但它們像是「接力賽」：完成任務後把結果丟回來，彼此之間無法直接溝通。

如果 Subagents 是「分工」，那 Agent Teams 就是真正的「協作」。

Claude Code 推出了實驗性的 Agent Teams 功能，讓多個 Claude Code 實例組成團隊，擁有共享任務清單、跨 Agent 即時通訊，以及集中化的團隊管理。這不再只是把工作分出去再收回來 — 而是讓 AI 助手們像真正的開發團隊一樣，互相討論、挑戰彼此的觀點、自主協調工作。

⚠️ 實驗性功能提醒：Agent Teams 目前為實驗性功能，預設關閉。使用前需手動啟用，且存在已知限制。

Agent Teams 概覽：從單兵作戰到團隊協作

什麼是 Agent Teams？

Agent Teams 的核心架構很簡單：一個 Team Lead（團隊領導者）加上多個 Teammates（團隊成員）。

• Team Lead：你的主要 Claude Code session，負責建立團隊、分派任務、協調工作和整合成果
• Teammates：獨立的 Claude Code 實例，各自擁有完整的上下文窗口，能獨立執行任務
• Task List：共享的任務清單，所有成員都能查看和認領
• Mailbox：訊息系統，成員之間可以直接通訊

與 Subagents 最關鍵的差異在於：Teammates 之間可以直接對話。這不是 hub-and-spoke（中心輻射式）的架構，而是 mesh（網狀）的通訊模型。

Agent Teams 架構圖

graph TB
    U[使用者] --> L[Team Lead<br/>主要 Claude Code Session]

    L --> T1[Teammate 1<br/>安全審查]
    L --> T2[Teammate 2<br/>效能分析]
    L --> T3[Teammate 3<br/>測試覆蓋]

    T1 <--> T2
    T2 <--> T3
    T1 <--> T3

    L --- TL[共享任務清單<br/>Task List]
    L --- MB[訊息信箱<br/>Mailbox]
    L --- CF[團隊設定<br/>Config]

    TL --- T1
    TL --- T2
    TL --- T3

    subgraph 專案上下文
        CL[CLAUDE.md]
        MCP[MCP Servers]
        SK[Skills]
    end

    CL --> T1
    CL --> T2
    CL --> T3

    style U fill:#e1f5fe
    style L fill:#e1f5fe
    style T1 fill:#fff3e0
    style T2 fill:#fff3e0
    style T3 fill:#fff3e0
    style TL fill:#c8e6c9
    style MB fill:#c8e6c9
    style CF fill:#c8e6c9

Agent Teams vs Subagents：核心差異

一句話總結：當你的工作者只需要「完成任務回報」時，用 Subagents；當他們需要「互相分享發現、挑戰觀點、自主協調」時，用 Agent Teams。

graph LR
    subgraph Subagents 模式
        MA[主 Agent] --> SA1[Subagent 1]
        MA --> SA2[Subagent 2]
        MA --> SA3[Subagent 3]
        SA1 -->|回報結果| MA
        SA2 -->|回報結果| MA
        SA3 -->|回報結果| MA
    end

    subgraph Agent Teams 模式
        TL[Team Lead] --> TM1[Teammate 1]
        TL --> TM2[Teammate 2]
        TL --> TM3[Teammate 3]
        TM1 <-->|直接通訊| TM2
        TM2 <-->|直接通訊| TM3
        TM1 <-->|直接通訊| TM3
    end

    style MA fill:#e1f5fe
    style SA1 fill:#fff3e0
    style SA2 fill:#fff3e0
    style SA3 fill:#fff3e0
    style TL fill:#e1f5fe
    style TM1 fill:#c8e6c9
    style TM2 fill:#c8e6c9
    style TM3 fill:#c8e6c9

啟用與基本設定

啟用 Agent Teams

Agent Teams 預設為關閉狀態。你可以透過兩種方式啟用：

方式一：settings.json

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

方式二：環境變數

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

建立你的第一個 Agent Team

啟用後，直接用自然語言告訴 Claude 你要建立團隊：

我正在設計一個 CLI 工具，幫助開發者追蹤 codebase 中的 TODO 註解。
建立一個 agent team 從不同角度探索這個問題：
一個 teammate 負責 UX 設計，一個負責技術架構，一個扮演 devil's advocate。

Claude 會自動：

1. 建立團隊和共享任務清單
2. 為每個角色產生獨立的 Teammate
3. 讓 Teammates 各自探索問題
4. 整合所有發現
5. 工作完成後清理團隊資源

你也不需要主動要求 — 如果 Claude 判斷你的任務適合多人協作，它可能會主動建議建立 Agent Team，你確認後再執行。

團隊資料儲存位置

Agent Teams 的資料儲存在本地：

~/.claude/teams/{team-name}/config.json    # 團隊設定（成員名稱、ID、類型）
~/.claude/tasks/{team-name}/               # 共享任務清單

團隊設定檔包含 members 陣列，記錄每個 Teammate 的名稱、agent ID 和類型。Teammates 可以讀取這個檔案來發現其他團隊成員。

顯示模式詳解

In-process 模式

所有 Teammates 都在你的主要終端機內運行。這是預設模式，不需要額外安裝任何工具。

鍵盤操作：

Split Panes 模式

每個 Teammate 擁有獨立的終端面板，你可以同時看到所有人的輸出，點擊面板即可直接互動。

前置需求：

• tmux：透過系統套件管理器安裝（brew install tmux）
• iTerm2：安裝 it2 CLI，並在 iTerm2 → Settings → General → Magic 中啟用 Python API

💡 提示：tmux 在 macOS 上表現最佳。在 iTerm2 中使用 tmux -CC 是建議的進入方式。

顯示模式對比

設定顯示模式

settings.json 設定：

{
  "teammateMode": "in-process"
}

可選值：

• "auto"（預設）：如果已在 tmux session 內則使用 split panes，否則使用 in-process
• "in-process"：強制使用 in-process 模式
• "tmux"：啟用 split-pane 模式，自動偵測 tmux 或 iTerm2

CLI flag 覆蓋（單次 session）：

claude --teammate-mode in-process

團隊管理與協調

指定 Teammates 和模型

Claude 會根據任務自動決定 Teammates 數量，但你也可以明確指定：

建立一個 4 人團隊來並行重構這些模組。
每個 teammate 使用 Sonnet 模型。

任務管理系統

共享任務清單是團隊協調的核心。任務有三種狀態和依賴管理機制：

三種任務狀態：

依賴管理：任務可以依賴其他任務。當一個 Teammate 完成某任務時，依賴於該任務的其他任務會自動解除封鎖。帶有未完成依賴的任務無法被認領。

任務分配方式：

• Lead 指派：告訴 Lead 把哪個任務分給哪個 Teammate
• 自動認領：Teammate 完成當前任務後，自動認領下一個未分配、未被封鎖的任務

File Locking 防衝突：當多個 Teammates 同時嘗試認領同一任務時，系統使用 file locking 機制防止競爭條件。

直接與 Teammates 互動

每個 Teammate 都是完整、獨立的 Claude Code session。你可以直接與任何 Teammate 通訊，給予額外指示、追問問題或調整方向。

In-process 模式：

1. Shift+Up/Down 選擇 Teammate
2. 輸入文字發送訊息
3. Enter 進入 Teammate 的 session 查看詳情
4. Escape 中斷當前回合
5. Ctrl+T 切換任務清單

Split Panes 模式：

• 直接點擊 Teammate 的面板進行互動
• 每個 Teammate 擁有自己的完整終端視圖

計畫審批機制

對於複雜或高風險的任務，你可以要求 Teammate 在實作前先規劃方案：

產生一個架構師 teammate 來重構認證模組。
在他做任何修改之前，要求計畫審批。

graph TD
    A[Teammate 進入唯讀 Plan Mode] --> B[分析程式碼並擬定計畫]
    B --> C[向 Lead 提交計畫審批請求]
    C --> D{Lead 審查計畫}

    D -->|通過| E[Teammate 離開 Plan Mode]
    E --> F[開始實作]

    D -->|退回| G[Lead 提供修改回饋]
    G --> H[Teammate 根據回饋修訂計畫]
    H --> C

    style A fill:#e1f5fe
    style D fill:#fff3e0
    style F fill:#c8e6c9
    style G fill:#ffcdd2

影響 Lead 審批判斷的方式：在你的 prompt 中加入審批標準：

只有包含測試覆蓋的計畫才能通過審批。
拒絕任何修改資料庫 schema 的計畫。

Lead 會根據這些標準自主做出審批決策。

Delegate Mode：純協調模式

預設情況下，Lead 有時候會「忍不住」自己動手實作任務，而不是等 Teammates 完成。Delegate Mode 限制 Lead 只能使用協調相關的工具：產生 Teammate、發送訊息、關閉 Teammate 和管理任務。

啟用方式：先建立團隊，然後按 Shift+Tab 切換到 delegate mode。

適用場景：

• 你希望 Lead 純粹做「拆解工作、分配任務、整合成果」
• 避免 Lead 自己寫程式碼而忽略了協調職責
• 大型團隊（4+ Teammates）時，協調本身就是全職工作

團隊生命週期管理

關閉單一 Teammate：

請讓 researcher teammate 關閉

Lead 會發送關閉請求，Teammate 可以同意（優雅退出）或拒絕（附帶說明原因）。

清理整個團隊：

清理團隊

⚠️ 重要：務必透過 Lead 執行清理。先關閉所有 Teammates，再執行團隊清理。Teammate 不應該自行執行清理，因為它們的團隊上下文可能無法正確解析，可能導致資源處於不一致狀態。

通訊架構深度解析

Mailbox 訊息系統

Agent Teams 的通訊透過 Mailbox 系統實現，支援兩種訊息類型：

💡 注意：broadcast 的 token 成本隨團隊規模成倍增長，請謹慎使用。

自動送達機制：

• Teammate 發送的訊息會自動送達收件者，Lead 不需要手動轉發
• Teammate 完成工作並停止時，會自動通知 Lead
• 所有 Agent 都能查看任務狀態並認領可用的工作

Context 與權限

Context 載入：

• 每個 Teammate 在產生時會載入與一般 session 相同的專案上下文：CLAUDE.md、MCP servers、Skills
• Teammate 會收到 Lead 的 spawn prompt（啟動提示詞）
• Lead 的對話歷史不會傳遞給 Teammates

權限繼承：

• Teammates 啟動時繼承 Lead 的權限設定
• 如果 Lead 使用 --dangerously-skip-permissions，所有 Teammates 也會如此
• 產生後可以個別調整 Teammate 的權限模式
• 但無法在產生時為個別 Teammate 設定不同權限

完整工作流程

sequenceDiagram
    participant U as 使用者
    participant L as Team Lead
    participant T1 as Teammate 1
    participant T2 as Teammate 2
    participant TL as 共享任務清單

    U->>L: 描述任務需求
    L->>L: 分析任務，決定團隊結構

    L->>T1: 產生 Teammate 1（含 spawn prompt）
    L->>T2: 產生 Teammate 2（含 spawn prompt）
    L->>TL: 建立任務清單

    T1->>TL: 認領任務 A
    T2->>TL: 認領任務 B

    T1->>T1: 執行任務 A
    T2->>T2: 執行任務 B

    T1->>T2: 分享發現（直接通訊）
    T2->>T1: 挑戰觀點（直接通訊）

    T1->>TL: 標記任務 A 完成
    T1->>TL: 認領任務 C（原被 A 封鎖）

    T2->>TL: 標記任務 B 完成
    T2->>L: 通知完成（自動送達）

    T1->>TL: 標記任務 C 完成
    T1->>L: 通知完成（自動送達）

    L->>L: 整合所有成果
    L->>U: 報告最終結果
    L->>T1: 發送關閉請求
    L->>T2: 發送關閉請求
    L->>L: 清理團隊資源

最佳使用案例

案例 1：並行 Code Review

單一 reviewer 往往會偏向某一類問題。把 review 標準拆分成獨立領域，安全性、效能和測試覆蓋率都能獲得全面、同步的關注。

建立一個 agent team 來 review PR #142。產生三個 reviewer：
- 一個專注安全性影響
- 一個檢查效能衝擊
- 一個驗證測試覆蓋率
讓他們各自 review 後彙報發現。

運作方式：

• 三個 reviewer 從相同的 PR 出發，但各自套用不同的審查濾鏡
• Lead 在三個人都完成後，跨領域整合發現
• 每個 reviewer 不會被其他人的關注點分散注意力

案例 2：競爭假設調查

當根因不明確時，單一 Agent 往往找到一個合理解釋就停止調查了。這個 prompt 透過讓 Teammates 互相對抗來克服錨定偏見（anchoring bias）。

使用者回報 app 在傳送一則訊息後就斷線，而不是保持連線。
產生 5 個 agent teammates 調查不同的假設。
讓他們互相交流，嘗試推翻彼此的理論，像科學辯論一樣。
將最終共識更新到 findings 文件中。

為什麼這樣做有效：

辯論結構是關鍵機制。循序調查會受到錨定效應影響：一旦探索了某個理論，後續調查就會偏向它。讓多個獨立調查者主動嘗試推翻彼此的結論，最後存活下來的理論更可能是真正的根因。

案例 3：跨層協調開發

需要同時修改前端、後端和測試時，每一層由不同的 Teammate 負責。

建立一個 agent team 來實作新的使用者資料 API：
- 一個 teammate 負責後端 API 端點（src/api/）
- 一個 teammate 負責前端整合（src/components/）
- 一個 teammate 負責測試（tests/）

後端 teammate 需要計畫審批才能開始。
前端 teammate 依賴後端 API 定義。
測試 teammate 在後端和前端都完成後再開始。

運作方式：

• Lead 建立帶有依賴關係的任務清單
• 後端 Teammate 先在 Plan Mode 下規劃，Lead 審批後開始實作
• 後端完成 API 定義後，前端 Teammate 自動收到通知並開始整合
• 兩者都完成後，測試 Teammate 的任務自動解除封鎖

實戰進階技巧

提供足夠的上下文

Teammates 會自動載入專案上下文（CLAUDE.md、MCP servers、Skills），但不會繼承 Lead 的對話歷史。在 spawn prompt 中包含任務特定的細節：

好的範例：

產生一個安全審查 teammate，prompt 如下：
「審查 src/auth/ 的認證模組是否有安全漏洞。重點關注 token 處理、
session 管理和輸入驗證。這個 app 使用存在 httpOnly cookies 中的
JWT token。請將問題按嚴重程度分級回報。」

差的範例：

產生一個 teammate 來看看 auth 模組

差在哪？沒有說明要看什麼、重點在哪、使用了什麼技術、期望什麼格式的輸出。

任務粒度的拿捏

💡 建議：每個 Teammate 分配 5-6 個任務，讓大家都保持忙碌，也讓 Lead 能在某人卡住時重新分配工作。

避免檔案衝突

兩個 Teammates 同時編輯同一個檔案會導致覆寫。拆分工作時確保每個 Teammate 擁有不同的檔案集：

# 好的分工
Teammate 1: src/api/users.ts, src/api/auth.ts
Teammate 2: src/components/UserProfile.tsx, src/components/LoginForm.tsx
Teammate 3: tests/api/users.test.ts, tests/api/auth.test.ts

# 差的分工
Teammate 1: 重構 src/api/users.ts 的前半部
Teammate 2: 重構 src/api/users.ts 的後半部  ← 衝突！

監控與引導

不要讓團隊無人監管太久。定期做這些事：

• 檢查進度：查看 Teammates 的工作狀況
• 調整方向：發現方向偏差時及時修正
• 整合發現：在中途就開始整合，不要等到最後
• 主動干預：如果 Lead 開始自己做事而不是委派，告訴它：

等你的 teammates 完成任務後再繼續

Token 使用與成本考量

Agent Teams 的 token 使用量顯著高於單一 session，因為每個 Teammate 都有獨立的上下文窗口。

原則：對於研究、review 和新功能開發，額外的 token 通常物有所值。對於例行任務，單一 session 更具成本效益。

常見問題與故障排除

Teammates 沒有出現

• In-process 模式下：Teammates 可能已在運行但不可見。按 Shift+Down 循環切換
• 任務不夠複雜：Claude 會根據任務判斷是否需要建立團隊，太簡單的任務不會觸發
• Split panes 模式下：確認 tmux 已安裝且在 PATH 中

  which tmux
  

• iTerm2：確認 it2 CLI 已安裝，且 Python API 已在偏好設定中啟用

過多權限提示

Teammate 的權限請求會冒泡到 Lead，造成頻繁中斷。解法：在產生 Teammates 前，先在權限設定中預先核准常見操作。

Lead 提前結束工作

Lead 可能在所有任務實際完成前就判斷團隊已完工。解法：

繼續工作，等所有 teammates 完成任務後再結束。

如果 Lead 開始自己做事而不是委派，也可以告訴它等待。

孤立的 tmux sessions

如果團隊結束後 tmux session 殘留：

# 列出所有 sessions
tmux ls

# 刪除特定 session
tmux kill-session -t <session-name>

已知限制

Agent Teams 仍為實驗性功能，目前已知的限制：

💡 好消息：CLAUDE.md 正常運作！Teammates 會讀取工作目錄中的 CLAUDE.md 檔案，你可以用它為所有 Teammates 提供專案特定的指引。

總結與展望

Agent Teams 代表了 AI 輔助開發從「單一助手」到「團隊協作」的重要演進。回顧這個脈絡：

1. 單一 Agent：一個 Claude Code 處理所有事情
2. Subagents：分工但不協作，hub-and-spoke 模式
3. Agent Teams：真正的團隊協作，mesh 通訊模型

雖然目前仍是實驗性功能，但 Agent Teams 已經展現了強大的潛力。建議從研究型任務開始嘗試 — review PR、調查 bug、探索技術方案 — 這些任務有明確的邊界，不需要寫程式碼，能讓你在低風險的環境下體驗多 Agent 協作的威力。

當你準備好了，再逐步嘗試並行開發、跨層協調等更進階的用法。記住：好的工具不在於它有多強大，而在於你是否知道什麼時候該用它、什麼時候不該用它。

相關文章

• 如何有效使用 Claude Code 子 Agents — Subagents 基礎概念與實戰
• Claude Code Subagents 與 Plan Mode：智能協作新紀元 — Subagent 進階功能與 Plan Mode 深度解析
• Claude Code Skills 與 Sandbox：擴展性與安全性雙提升 — Skills 系統與安全沙盒
• Claude Code Hooks 系統與遷移指南 — 工作流程自動化