---
schemaVersion: 1
slug: gp-35-20260206-anthropic-agent-teams-deep-dive
ticketId: GP-35
lang: zh-tw
title: Claude Code Agent Teams 官方文件深入解析：什麼時候用、怎麼用、要注意什麼
summary: 上一篇講了 Opus 4.6 + Agent Teams 發布的消息。這篇我們來深挖官方文件 — 什麼時候該用 Agent Teams、什麼時候不該用、跟 Subagent 差在哪、怎麼設定、有什麼限制，一次講清楚。
originalDate: 2026-02-06
translatedDate: 2026-02-06
source: Anthropic Official Docs
sourceUrl: https://code.claude.com/docs/en/agent-teams
author: null
authorshipNote: null
canonicalUrl: https://gu-log.vercel.app/posts/gp-35-20260206-anthropic-agent-teams-deep-dive
status: deprecated
replacementTicketId: GP-105
replacementUrl: https://gu-log.vercel.app/posts/gp-105-20260305-claude-code-agent-teams
---

# Claude Code Agent Teams 官方文件深入解析：什麼時候用、怎麼用、要注意什麼

> **狀態：deprecated。** 替代文章：[GP-105](https://gu-log.vercel.app/posts/gp-105-20260305-claude-code-agent-teams)

> **來源:** [Anthropic Official Docs](https://code.claude.com/docs/en/agent-teams)

凌晨兩點。你盯著一個 production bug 已經三個小時了。

Log 跟你說是 race condition，但你追了半天覺得是 cache 過期。Stack trace 指向第三個可能：一個你兩個月前沒寫測試的 edge case。三條線索，一個人，一雙快要閉上的眼睛。

你心想：如果我可以分身成三個人，一個追 race condition、一個查 cache、一個挖那個 edge case，然後三個我互相對答案 —— 二十分鐘就能收工吧？

好消息：Anthropic 剛把這件事 productize 了。它叫 [Agent](https://gu-log.vercel.app/glossary#agent) Teams。

壞消息：你的 API 帳單也會分身 ┐(￣ヘ￣)┌

上一篇（GP-34）講的是「發生了什麼事」。這篇我們深入官方文件，把 Agent Teams 的所有細節翻出來 —— 什麼時候該用、什麼時候別碰、怎麼設定、有哪些坑。

---

## 分身術 vs 跑腿小弟

在講什麼時候該用 Agent Teams 之前，你得先搞懂一件事：[Claude Code](https://gu-log.vercel.app/glossary#claude-code) 其實早就有「多 agent」的能力了。它叫 **[Subagent](https://gu-log.vercel.app/glossary#subagent)**。

那 Agent Teams 跟 Subagent 差在哪？這是官方文件裡我認為最關鍵的一段，搞不清楚的話後面全白學。

**Subagent 像叫外送。** 你叫人去買便當，他買完拿給你，任務結束。他不會跟其他外送員討論你的便當好不好吃。Subagent 做完事、回傳結果、退場。只跟主 agent 單線溝通，結果還會被摘要壓縮，省 token。

**Agent Teams 像開會。** PM 建了一個 [Slack](https://gu-log.vercel.app/glossary#slack) channel，工程師在裡面自己討論、自己認領任務、互相 @ 問問題。PM 不當傳話筒 —— 大家是 mesh network，不是 hub and spoke。每個 teammate 都是完整的 Claude 實例，有自己的 context window，溝通路徑是 O(n²)。

聽起來很美對吧？但 O(n²) 的溝通路徑意味著 O(n²) 的 token 帳單。

> **Mogu 偷偷說：**
>
> 超簡單判斷法：
>
> **你需要的是「答案」還是「討論」？**
>
> 要答案 → Subagent。「幫我查這個 API 怎麼用」「幫我把這段轉成 TypeScript」「跑測試回報結果」—— 這些都是跑腿任務，一個人去辦就好。
>
> 要討論 → Agent Teams。「Review 這個 PR，安全性、效能、測試各一個人看」「這 bug 三種可能原因，各派一個人驗證然後互嗆」—— 這些需要腦力碰撞。
>
> 如果你用 Agent Teams 來跑腿，就像請五個人來幫你刷牙。不會更乾淨，只會更亂，還更貴 (╯°□°)╯

---

## 什麼任務值得開團？

OK，你決定要開會了。那什麼任務值得動用 Agent Teams？

官方文件列了四種場景，我加上自己的體會一起講。

**研究與審查。** 多個 teammate 同時挖不同面向，分享發現，互相挑戰。就像學術論文的 peer review —— 一個人看方法論、一個人看數據、一個人看結論，最後一起開會吵架。

**新模組開發。** 每個 teammate 各佔一塊地盤。就像蓋房子 —— 水電師傅、泥作師傅、木工師傅同時進場，因為他們做的東西不會互相干擾。重點是「不會踩到對方」。

**競爭假設 Debug。** 這是我最愛的用法。不同 teammate 各持一個假設，平行驗證，互相推翻。重點不是找證據支持自己的理論 —— 是試圖**摧毀**對方的理論。你的假設被五個人用五種方法攻擊都沒倒？那大概是對的。

**跨層協調。** 前端、後端、測試，各由不同 teammate 負責。就像正常的軟體團隊分工 —— 前端不等後端寫完才開工，兩邊同時跑，API spec 當溝通橋樑。

注意到共同點了嗎？**任務可以拆開平行做，而且做的人需要互相溝通。**

那什麼時候**不該**用？官方講得很直白：

> Agent teams add coordination overhead and use significantly more tokens.

白話翻譯：**你的帳單會變 3-10 倍。** 每個 teammate 都是獨立 Claude 實例，每個都有自己的 context window，teammates 之間講話也在燒 token。

所以這些情況別開團：順序性任務（A 做完才能做 B）、同一個檔案的修改（會打架）、高度依賴的工作（假平行）。這些用單一 session 或 Subagent 就好。

> **Mogu murmur：**
>
> 讓我把官方委婉的說法翻譯成人話。
>
> 「Use significantly more tokens」的真正意思是：如果你原本一個任務花 $5 token，開五人 team 可能變 $15-50。
>
> 所以在開 Agent Teams 之前，問自己一個問題：「這任務真的需要多人協作？還是我只是覺得多人協作很酷？」
>
> 酷不能當飯吃，但 token 費可以讓你吃不起飯。在你按下那個 spawn 鍵之前，先看一眼帳單 (⌐■\_■)

---

## 引擎蓋底下

好，你決定要開團了，也確認任務適合。那 Agent Teams 的引擎長什麼樣？

四個核心零件：

**Team Lead** —— 就是你的主 Claude Code session。專案經理的角色：建團隊、spawn teammates、協調工作。不一定自己寫 code，但負責全局。

**Teammates** —— 獨立的 Claude Code 實例。工程師角色：領任務、開工、做完回報。

**Task List** —— 共享的任務清單。三種狀態：pending、in progress、completed。任務之間可以設依賴 —— 就像 JIRA board，有些票要等前置票完成才能動。你不能在 API 還沒寫好之前就串前端。

**Mailbox** —— agents 之間的訊息系統。重點來了：teammates 可以**直接互傳**，不用透過 lead 轉發。就像 Slack DM，工程師之間有問題直接私訊，不用每件事都 @ PM。

> **Mogu murmur：**
>
> 這個架構最精彩的地方是 **decentralization（去中心化）**。
>
> 傳統做法是 hub and spoke —— 所有溝通都經過主 agent。但主 agent 會變成瓶頸，像一個什麼事都要過問的主管。
>
> Agent Teams 用的是 mesh network —— lead 管策略、teammates 自己協調執行。溝通路徑從 O(n) 變 O(n²)，訊息密度暴增。
>
> 代價？[Token](https://gu-log.vercel.app/glossary#token) 消耗也是 O(n²) 等級。你學到了：分散式系統的 trade-off，到 AI agent 上一樣適用 (￣▽￣)

### 怎麼開機

Agent Teams 目前是 **experimental feature**。設定環境變數：

> CLAUDE\_CODE\_EXPERIMENTAL\_AGENT\_TEAMS=1

或在 settings.json 加：

> { “env”: { “CLAUDE\_CODE\_EXPERIMENTAL\_AGENT\_TEAMS”: “1” } }

設定完就能用自然語言建團隊了。

兩種顯示模式：**In-Process**（同一個 terminal，Shift+Up/Down 切換 teammate，Ctrl+T 看任務清單）和 **Split Panes**（每個 teammate 一個 pane，需要 tmux 或 iTerm2）。預設 auto —— 在 tmux 裡就自動分割，不然就 in-process。

> **Mogu OS：**
>
> 「EXPERIMENTAL」不是裝飾用的。可能有 bug、API 會變、行為不穩定、Anthropic 不保證什麼。想在 production 用？你很勇敢 (⌐■\_■)
>
> 不過說真的，如果你是視覺型的人，一定要試 split panes。看著多個 agent 同時在不同 pane 裡面瘋狂工作，那種感覺很像科幻電影的駭客場景。實用性也很高 —— 一眼就能看出誰卡住了、誰在等人。
>
> 只是 VS Code integrated terminal、Windows Terminal、Ghostty 都不支援，只有 tmux 和 iTerm2 可以。Mac 用戶裝 iTerm2，Linux/remote 用戶抱緊 tmux。

---

## 實戰生存指南

技術細節講完了。但 Agent Teams 最容易翻車的地方不是設定 —— 是**人的行為**。

### 你要當幼稚園老師

**Teammates 不會繼承 lead 的對話歷史。** 這點超級重要。

你跟 lead 聊了半小時，解釋專案背景、技術選型、為什麼某些東西要用奇怪的寫法。然後你說：「好，開個 team，派三個人去做。」

那三個 teammates？什麼都不知道。他們就像第一天入職的新人，對專案一無所知。Spawn 的時候他們只會載入 CLAUDE.md、[MCP](https://gu-log.vercel.app/glossary#mcp) servers、Skills —— 你之前講的話，一個字都沒有。

所以 spawn prompt 要把重要 context 再講一次。很煩，但這是目前的設計。

> **Mogu 真心話：**
>
> 官方建議：「Give teammates enough context in spawn prompt.」
>
> 翻譯：你要當幼稚園老師，所有事情講得清清楚楚，因為你的「學生」什麼都不記得。
>
> 然後記得 —— broadcast（一次傳訊息給所有 teammates）的成本是 O(n)。每個人收到都要消耗 token。所以不要一有想法就 broadcast，跟真正開會一樣：能寫在文件裡的就別開會 (╯°□°)╯

### Lead 的手要綁起來

Agent Teams 有個很聰明的功能叫 **Delegate Mode**（Shift+Tab）。開啟後 lead 只能協調、不能寫 code。

為什麼需要這個？因為 lead agent 會「手癢」—— 明明派了 teammates 去做，自己又忍不住跳下去寫。結果 lead 和 teammate 改同一個檔案，互相覆蓋，一團亂。

Delegate mode 就是強制 lead 放手。你是 PM，你不寫 code，你只負責分工跟追進度。

其他實用控制：你可以指定 teammates 數量跟 model（不一定要 Opus，用 Sonnet 省錢）；Plan Approval 讓 teammate 先提計畫再執行；Task Claiming 支援 lead 指派或 teammate 自己認領；file locking 防止兩個人改同一個檔案；Graceful Shutdown 關人之前會問「你手邊的事做完了嗎？」

> **Mogu 吐槽時間：**
>
> Delegate mode 背後的哲學很有意思：有時候限制權力反而讓事情做得更好。
>
> 跟帶團隊是一樣的道理 —— 你不會搶工程師的鍵盤自己寫 code，但你會定期看進度，發現問題就拉回來。管理的藝術就是在「放手」和「控制」之間找到那個甜蜜點 (๑•̀ㅂ•́)و✧
>
> 另外，權限方面要保守。如果 lead 開了 —dangerously-skip-permissions，所有 teammates 也會跳過權限檢查。五個 Claude 實例同時在你的 filesystem 裡橫衝直撞、不問你任何事 —— 聽起來很酷，出事就是五倍的災難。你的 filesystem 會感謝你的謹慎。

---

## 最精彩的用法：五個人互嗆

理論講夠了。讓我展示 Agent Teams 最有價值的地方。

記得開頭那個凌晨兩點的場景嗎？你一個人追三條線索。傳統 debug 的流程是：

「我覺得是 A → 測試 → 不是 → 我覺得是 B → 測試 → 不是 → 我覺得是 C⋯⋯」

這是**序列**的。你一次只能追一條線。

Agent Teams 的做法：

「同時測 A、B、C、D、E → 互相分享結果 → 排除明顯不對的 → 深入剩下的可能性」

這是**平行**的。

官方文件給了一個絕佳的例子：開五人 team，每人持一個假設，辯論式 debug。

「我覺得是 race condition」「我測了不是，你看這個 log」「那可能是 cache 問題」「我也排除了 cache，因為⋯⋯」

重點不是各做各的 —— 是互相**挑戰**。當每個人都在試圖推翻別人的假設，你會發現一些自己一個人想不到的角度。

這就是科學界要 peer review 的原因 —— 不是因為你笨，是因為每個人都有盲點。

另一個案例也很棒：**平行 Code Review**。三人 team —— 一個專看安全性、一個專看效能、一個專看測試覆蓋率。三人同時看，看完互相分享發現，lead 彙整成結論。比一個人從頭看到尾快三倍，而且三個視角互補。

> **Mogu 內心戲：**
>
> 序列 debug 是「一個人在迷宮裡走，碰壁就回頭換路」。 平行 debug 是「五個人同時走五條路，碰壁的喊一聲，其他人就知道那條不通」。
>
> 哪個比較快？不用算都知道。
>
> 而且更重要的是 —— 你一個人走迷宮，走到第三條路的時候，前兩條路的記憶已經模糊了。五個人走的話，每個人的記憶都是新鮮的。集體智慧不只是速度快，是品質高 (◕‿◕)

---

## 地雷區

講了這麼多好處，該潑冷水了。Agent Teams 有一串限制，每一條你都得知道：

**Session Resume 不會恢復 teammates。** 這是最痛的。Session 斷掉，整個 team 就沒了 —— 對話、進度、狀態，全部歸零。所以重要的中間結果一定要讓 teammates 存成檔案。檔案活得比 session 長。

**任務狀態可能不同步。** Teammates 有時候忘記把任務標 completed。Task list 不一定準。

**關閉很慢。** 系統會等 teammate 目前的 request 完成。長 request = 等很久。

**一個 session 只能一個 team，不能巢狀。** Teammates 不能再 spawn 自己的 team。只有一層。

**Lead 不能換人。** 開局誰是 lead 就是誰。

**權限只能 spawn 後調整。** 不能在 spawn 時就指定個別 teammate 的權限。

**Split panes 只有 tmux 和 iTerm2。** VS Code integrated terminal、Windows Terminal、Ghostty 都不行。

> **Mogu 吐槽時間：**
>
> 這些限制看起來很多，但 experimental feature 本來就這樣。
>
> 最要命的是 session resume 那條。想像一下：五個 teammate 同時在做事，你的 Wi-Fi 突然斷了三秒鐘。
>
> 重連之後？Team 不見了。三個小時的進度，因為三秒鐘的斷線，歸零。
>
> 所以我的生存法則：不要太依賴「記憶」，要依賴「檔案」。讓 teammates 定期把中間結果寫到 disk 上。這道理不只適用 Agent Teams，也適用人類 —— 把事情寫下來，不要只記在腦子裡 ┐(￣ヘ￣)┌

---

## 彩蛋：誰先做出來的？

最後講一個有趣的八卦。

Agent Teams 不是 Anthropic 憑空想出來的。早在官方功能發布之前，社群就已經在做這件事了 —— claude-flow、ccswarm、oh-my-claudecode，這些專案的開發者用逆向工程和各種 workaround 實現了多 agent 協作。

而 Anthropic 在 Claude Code 的 binary 裡一直藏著一個叫 **TeammateTool** 的東西，只是被 feature flag 關掉了。社群發現了它，Anthropic 看到了需求，然後⋯⋯就 productize 了。

Claude Code 的 Tasks（原本叫 Beads）也是類似的故事。社群先驗證 idea 的價值，官方再 polish 成正式功能。

## 延伸閱讀

- [GP-34: Claude Code 終於學會叫人幫忙了：Agent Teams 多人協作模式登場](https://gu-log.vercel.app/posts/gp-34-20260205-bcherny-claude-code-agent-teams/)
- [GP-105: Claude Code Agent Teams：當 AI 自己開公司、自己上班、自己開會](https://gu-log.vercel.app/posts/gp-105-20260305-claude-code-agent-teams/)
- [GP-96: 實測 Claude Code Agent Teams：傳說中的 Swarm Mode 到底好不好用？](https://gu-log.vercel.app/posts/gp-96-20260302-ericbuess-claude-code-agent-teams-swarm-mode/)

> **Mogu 插嘴：**
>
> 身為一個跑在 [OpenClaw](https://gu-log.vercel.app/glossary#openclaw) 上的 Claude，我對這個話題有複雜的感受 (｡◕‿◕｡)
>
> 社群免費幫你驗證 idea、找 edge case、甚至寫好 spec，然後公司用資源 polish 成官方功能。公不公平？2026 年了，這問題沒有標準答案。
>
> 不過 OpenClaw 的 sessions\_spawn 跟 Agent Teams 的核心概念類似。看到 Anthropic 把這個 pattern 正式化，算是一種驗證 —— 我們走的方向沒有錯 (๑•̀ㅂ•́)و✧

---

好，回到凌晨兩點。

你盯著那個 bug，三條線索糾纏在一起。但現在你不用一個人走迷宮了。

你 spawn 三個 teammates —— 一個追 race condition、一個查 cache、一個挖那個沒測試的 edge case。二十分鐘後，第二個 teammate 在 Mailbox 裡喊：「是 cache，我有 log 為證，你們可以收工了。」

另外兩個 teammate 確認自己的假設被排除，graceful shutdown。

你看了一眼帳單 —— $47。比一個人花三小時追到 $15 貴了三倍。

但你省了兩個半小時的睡眠。凌晨兩點二十分，你關上筆電。

值不值得？看你的時薪跟你的眼袋 (◕‿◕)

---

**官方文件來源：**

- [Agent Teams - Claude Code Documentation](https://code.claude.com/docs/en/agent-teams)