Claude Code 的 Agent Teams（代理團隊）是一個實驗性功能，能讓多個 Claude Code instance 同時工作、互相溝通、共享任務。這篇文章完整記錄了我從啟用設定、觸發條件研究，到規劃用 Agent Teams 重建電商 OMS 系統的全過程。
Claude Code Agent Teams 是什麼？
Agent Teams 讓你可以在 Claude Code 中協調多個獨立的 Claude instance 同時工作。一個 session 扮演 Team Lead（團隊領導），負責建立團隊、分配任務、彙整結果；其他 session 是 Teammates（隊友），各自擁有獨立的 context window，能互相發送訊息、共享任務清單，甚至互相挑戰彼此的觀點。
Agent Teams 和 Subagent 有什麼不同？
Claude Code 原本就有 Subagent（子代理）功能。兩者的核心差異在於：
| 比較項目 | Subagent（子代理） | Agent Teams（代理團隊） |
|---|---|---|
| Context Window | 獨立，結果摘要回傳給主代理 | 獨立，完全獨立運作 |
| 溝通方式 | 只能回報結果給主代理 | 隊友之間可以直接互相溝通 |
| 協調方式 | 主代理管理所有工作 | 共享任務清單，自主認領和協調 |
| 適合場景 | 專注的任務，只需要結果 | 需要討論、辯論和協作的複雜工作 |
| Token 成本 | 較低 | 較高（每個隊友都是完整 instance） |
簡單來說：Subagent 是派工，Agent Teams 是開會。Subagent 做完就回報；Agent Teams 的隊友會互相討論、質疑、協商，最後由 Lead 彙整共識。
如何啟用 Claude Code Agent Teams？
Agent Teams 預設是關閉的。網路上有些文章會提到在實驗性功能區塊加入 "agentTeams": true，但根據 Claude Code 官方文件，正確的啟用方式是透過環境變數設定：
編輯 ~/.claude/settings.json，加入以下內容：
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}如果你的 settings.json 已經有其他設定，直接在最外層加入 "env" 區塊即可：
{
"model": "opus[1m]",
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
"hooks": { ... },
"statusLine": { ... },
"enabledPlugins": { ... }
}加完後重啟 Claude Code 即可生效。
什麼條件會觸發 Agent Teams？
這是很多人的疑問：啟用後，Agent Teams 會自動運作嗎？
答案是不會。啟用環境變數只是「解鎖」這個功能，實際使用需要觸發。Agent Teams 有兩種啟動方式：
方式一：你主動要求（最常見）
在對話中明確告訴 Claude 要建立團隊，並描述任務和角色分工：
建立一個 agent team 來做 code review PR #142：
- 一個負責安全性檢查
- 一個負責效能分析
- 一個負責測試覆蓋率方式二：Claude 主動提議
如果 Claude 判斷你的任務適合平行處理，它可能會建議建立團隊。但一定會先等你確認才會執行——Claude 不會未經同意就自動建立團隊。
Agent Teams 最適合哪些場景？
根據官方文件和實際使用經驗，Agent Teams 最能發揮價值的場景包括：
1. 多角度研究與 Code Review
單一 reviewer 容易偏向某一類問題。拆分成多個獨立的 reviewer，每人負責不同的審查維度（安全、效能、測試覆蓋），能確保每個面向都得到充分關注：
建立 agent team 來 review PR #142，三個 reviewer：
- Security reviewer：審查漏洞、Token 處理
- Performance analyst：profile 回應時間、識別瓶頸
- Test coverage checker：驗證邊界條件、找出未測試路徑2. 競爭假設 Debug
單一 agent 找到一個可能的原因就傾向停下來。用 Agent Teams 讓多個 agent 各自調查不同假設，並互相質疑，能找到更準確的根因：
用戶反映 app 斷線。建立 5 個 agent 調查不同假設，
讓他們互相辯論、嘗試推翻對方的理論，
像科學辯論一樣收斂到真正的原因。3. 跨層系統開發（前端 + 後端 + 事件流）
如果你的系統有天然的分層邊界，Agent Teams 非常適合。例如前端 + 後端 + Kafka/RabbitMQ 事件流架構：
| 層級 | 負責範圍 | 檔案獨立 |
|---|---|---|
| 前端 | UI、狀態管理、API 呼叫 | ✅ |
| 後端 | API、業務邏輯、DB 操作 | ✅ |
| 事件流 | Producer / Consumer、Topic、Event Schema | ✅ |
三層各自改各自的檔案，不會互相覆蓋——這是 Agent Teams 最關鍵的前提。
4. 新模組開發
各隊友負責不同的模組，互不干擾。隊友之間可以透過訊息協商介面契約（API schema、event schema），確保串接一致。
實戰：用 Agent Teams 重建電商 OMS 系統
以下是我規劃用 Agent Teams 從零重建電商 OMS（訂單管理系統）的實際策略。系統架構為前端 Vue 3 + 後端 Spring Boot + RabbitMQ 事件流，手上有舊系統的部分程式碼（主要是 Kafka Job 和 Topic 定義）。
分階段推進策略
大工程不能一口氣全丟進去。我把整個專案分成四個階段，每個階段用一個獨立的 Agent Team：
階段一（分析舊系統）
│
▼
階段二（架構設計） ← 這兩階段產出「文件」，是後續的基礎
│
▼
階段三（搭骨架）
│
▼
階段四（模組 A）──→ 階段四（模組 B）──→ 階段四（模組 C）
↑ 可以平行跑多個模組，只要模組間獨立階段一：逆向分析舊系統
即使舊系統程式碼不完整，在事件流架構中，Topic 表 + Job 就是系統的骨幹——它們描述了「系統裡發生了什麼事」和「發生後要做什麼」。
| 從 Topic / Job 能推出的 | 推導方式 |
|---|---|
| 完整業務流程 | Topic 的先後順序 = 業務 workflow |
| 領域模型 | Event 裡帶的欄位 = 核心資料結構 |
| 系統邊界 | 誰 produce、誰 consume = 服務邊界 |
| 業務規則 | Job 裡的判斷邏輯 = 業務規則 |
| 錯誤處理 | DLQ / retry topic = 異常流程 |
建立 agent team 來從事件流反推舊系統全貌：
- 事件流考古師：分析 Topic 表，梳理業務 workflow 和事件順序
- Job 分析師：分析每個 Job 的訂閱/產出 topic 和內部邏輯
- 領域建模師：從事件和 Job 反推 Entity、關聯、狀態機
- 缺口分析師：列出「已知 vs 未知」，產生問題清單給我確認事件流全景圖範例：
[用戶下單]
→ order-created
→ Job A: 驗證庫存 → inventory-checked
→ Job B: 扣減庫存 → inventory-reserved
→ Job C: 建立付款單 → payment-pending
→ [用戶付款] → payment-received
→ Job D: 確認訂單 → order-confirmed
→ Job E: 建立出貨單 → shipment-created事件流架構的最大優勢就是「事件即文件」——Topic 表本身就是系統行為的完整記錄。
階段二：架構設計
建立 agent team 來設計新系統架構：
- 系統架構師：設計整體架構和三層邊界
- API 設計師：設計 RESTful API 契約（OpenAPI spec）
- 事件設計師：設計 Topic 結構、Event Schema、Partition 策略
- DB 設計師：設計資料模型和 Migration 策略
要求所有人先規劃再實作（require plan approval）。
產出放在 docs/architecture/ 目錄下。階段三：搭建基礎骨架
建立 agent team 來搭建專案骨架：
- 前端工程師：Vue 3 + Vite 專案、路由、共用元件、API client
- 後端工程師：Spring Boot、Middleware、DB 連線、ORM、API 路由
- 事件流工程師：RabbitMQ Exchange/Queue 設定、Producer/Consumer 封裝、DLQ
- DevOps 工程師：Docker Compose 開發環境、CI/CD pipeline階段四：逐模組實作
建立 agent team 來實作「訂單模組」：
- 前端工程師：訂單列表頁、訂單詳情頁、建立訂單表單
- 後端工程師：訂單 CRUD API、業務驗證、權限控管
- 事件流工程師：order-created / order-updated 事件與 Consumer
- 測試工程師：每層的 unit test + 端到端整合測試
遵循 docs/architecture/ 下的 API spec 和 event schema。
每個業務模組重複這個步驟。Agent Teams 使用注意事項與限制
- Token 用量大幅增加：每個隊友都是完整的 Claude instance，成本線性增長。建議 3-5 個隊友為最佳。
- 每個階段重啟新 team：不要一個 team 跑到底，context 會太龐大。
- 文件是銜接關鍵：每個階段的產出文件放在固定目錄，下個 team 讀取作為輸入。
- 避免同檔衝突：確保每個隊友負責不同的檔案，同時編輯同一個檔案會導致覆蓋。
- 先定義介面契約：用
addBlockedBy設定任務依賴，讓架構師先定義好 API / Event Schema，再讓其他人開工。 - 不支援 session 恢復：
/resume和/rewind無法恢復進行中的隊友。 - 分割畫面需要 tmux：想同時看到所有隊友的輸出，需要安裝 tmux 或使用 iTerm2。
- 每個 session 只能有一個團隊，不支援巢狀團隊。
常見問題 FAQ
Q: Agent Teams 啟用後會自動觸發嗎？
不會。啟用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 只是解鎖功能。你需要在對話中明確要求建立團隊，或者 Claude 會在判斷適合時提議（但仍需你確認）。
Q: Agent Teams 和 Subagent 應該選哪個？
如果任務是「做完回報結果」就夠了，用 Subagent（成本低、速度快）。如果隊友需要「互相溝通、討論、質疑」，用 Agent Teams。
Q: Agent Teams 最多可以有幾個隊友？
沒有硬性限制，但官方建議 3-5 個隊友最佳。超過後協調開銷增加，效益遞減。每個隊友分配 5-6 個任務是比較理想的比例。
Q: 舊系統程式碼不完整，還能用 Agent Teams 分析嗎？
可以。在事件流架構中，Topic 表和 Job 程式碼就能推出大部分的業務流程。搭配 DB schema、UI 截圖、你的領域知識，通常能拼回 80-90% 的全貌。讓 Agent Teams 產出「缺口問題清單」，由你填補剩下的 10-20%。
Q: 用 Agent Teams 開發，Token 成本會增加多少？
每個隊友都是獨立的 Claude instance，Token 用量與隊友數量成正比。3 個隊友大約是單一 session 的 3-4 倍成本（包含通訊開銷）。對於需要深度多角度分析或平行開發的場景，額外成本通常是值得的。
結語
Claude Code Agent Teams 不是每個場景都需要，但對於有天然分層邊界的系統架構，它能顯著提升開發效率。核心原則是：
- 分階段推進，每個階段一個 team
- 文件驅動，每階段產出文件，下階段消費文件
- 明確分工，確保隊友不搶同一個檔案
- 善用舊系統資產，Topic 表和 Job 程式碼是被低估的金礦
不管你最終是否使用 Agent Teams，上面的分階段策略和事件流分析方法論，對任何系統重建專案都同樣適用。
本文整理自與 Claude Code (Opus 4.6) 的實際對話，以對話式探索逐步深入 Agent Teams 的應用場景。
發佈留言