跳轉到主要內容
這個單元解決什麼問題Sub Agent 是一次性子任務的執行者：spawn 後處理完返回結論，脈絡不延續。Agent Teams 是可定址、可持續對話、可協作的常駐代理：建立後保有身份，可收訊息、可與其他 Agent 互傳狀態、可搶任務。本單元釐清兩者的生命週期差異、各自的啟用方式，並列舉主從編排、平行獨立分工、Agent 間訊息往返三種協作模式，讓你在設計自動化流程時選對工具、不過度工程化。

​
學習目標

讀完本單元，你應該能夠：
  • 分清 Sub Agent（一次性 spawn、結論回傳主線、脈絡不延續）與 Agent Teams（可定址、持續存活、可協作）的本質差異。
  • 說出 Sub Agent 與 Agent Teams 各自的啟用方式及限制（截至 2026-06，Agent Teams 為實驗性功能）。
  • 列舉三種協作模式（主從編排、平行獨立分工、Agent 間訊息往返），並判斷各適用場景。
  • 判斷一個任務該用 Sub Agent、Agent Teams，還是根本不需要多代理。

​
1. 兩者定義與核心差異

Anthropic 在 Claude Code v2.1.32 起引入 Agent Teams [1]。它是相對於 04-5 Subagent 的另一層多代理機制：不是「一次 spawn 跑完就消失」，而是「多個 Claude Code 實例以 team 形式組成、共享 task list、互相傳訊、可被使用者與 lead 直接定址」。
命名澄清本單元以 Sub Agent 指 04-5 的 Subagent（一次性、隔離 context、回傳結論）；以 Agent Teams 指 Anthropic 文件中的 “agent teams” / teammate（持續、可定址、可協作）。Subagent 與 Agent Teams 是兩個獨立機制，可以並存：一個 session 內可以同時有 Subagent 與 Agent Teams，各自扮演不同角色。
核心差異（截至 2026-06 依官方 agent teams 章節 [1]）：
維度Sub AgentAgent Teams
生命週期任務結束即消滅持續存活直到 lead 拆解 team
可定址性不可定址（主動 spawn）可定址（lead / 隊友 / 使用者皆可指名）
上下文每次 spawn 全新跨輪次延續（teammate 持續累積自己的脈絡）
通訊方式只回傳結論給 caller透過 mailbox 雙向傳訊、共享 task list、idle notification
數量限制同一 session 內可多次 spawn一個 lead 同時只管一個 team [1]
巢狀不能 spawn Subagentteammate 不能 spawn team 或其他 teammate [1]
Token 成本較低（結論摘要回 caller）較高（每個 teammate 一個完整 context window）
適用場景一次性子任務、唯讀查詢、平行分工（結果不需互動）持續協作、需多輪反饋、需共享狀態、需被使用者直接介入
與 01-4 上下文工程的銜接Sub Agent 是「把大任務關到 swap partition」、主 RAM 只看到結論。Agent Teams 是「開了 N 個獨立 RAM、可彼此交換訊息」。前者省 context、後者買協作能力。選錯的代價是 token 燒完卻沒拿到結果，或為了省 token 把多輪對話硬塞進單一 context 使模型輸出品質下降。

​
2. 啟用方式

​
2.1 Sub Agent（04-5 已展開）

從主 session 或 Skill 用 Agent(<name>) 顯式叫用，或讓 Claude 依 description 自動委派。Subagent 定義在 .claude/agents/、使用者層 ~/.claude/agents/、plugin agents/、managed 設定或 --agents CLI flag。生命週期就是「spawn → 跑任務 → 回傳結論 → 結束」。

​
2.2 Agent Teams

截至 2026-06，Agent Teams 為實驗性功能，預設關閉 [1]。啟用方式： 
// .claude/settings.json 或 ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
或在 shell 啟動時設環境變數： 
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
啟用後，在對話中以自然語言請 Claude 建立 team： 
我要設計一套 CLI 工具追蹤 codebase 裡的 TODO 註解。
建一個 agent team，從三個角度探索：UX、技術架構、唱反調。
Claude 會建立 team、spawn teammates、各自探索、合成結論 [1]。
Agent Teams 的當前限制
  • 預設關閉，需 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 啟用。
  • in-process 模式下 /resume 與 /rewind 不還原 teammates；resume 後 lead 可能嘗試聯絡不存在的 teammate [1]。
  • task 狀態有時 lag（teammate 沒 mark completed 會卡住 dependent task）[1]。
  • 同一 lead 同時只管一個 team；要建新 team 先清掉舊的。
  • teammate 不能 spawn 自己的 team 或其他 teammate。
  • lead 是固定的，session 啟動後不能改。
  • 所有 teammate 啟動時繼承 lead 的權限模式；不能個別設。
  • split-pane 模式需要 tmux 或 iTerm2（VS Code integrated terminal、Windows Terminal、Ghostty 不支援）[1]。

​
2.3 顯示模式

Agent Teams 支援兩種顯示模式 [1]：
模式設定行為
in-process（預設 fallback）teammateMode: "in-process"所有 teammate 跑在主 terminal 內。Shift+Down 循環切換；可對任一 teammate 直接傳訊
split-paneteammateMode: "tmux"每個 teammate 一個 pane。需 tmux 或 iTerm2 + it2 CLI
預設 auto：在 tmux session 內啟動就用 split-pane，否則 in-process。要強制： 
claude --teammate-mode in-process
Windows 上要 split-pane：psmux 或 WSL 的 tmuxtmux 與 iTerm2 都不是 Windows native，Windows 使用者預設只會落到 in-process。要在 Windows 用 split-pane，兩條路：
  • psmux：Rust 寫的 Windows 原生終端多工器，相容既有 .tmux.conf，不需 WSL 或 Cygwin；在 psmux session 內啟動 Claude Code，teammate 會自動進獨立 pane。截至 2026-06 仍屬新專案（版本 0.1.x），導入前自評維護狀態 [4]。
  • WSL 內的 tmux：在 WSL 裝 tmux、於 WSL 終端跑 Claude Code，split-pane 與原生 tmux 行為一致；前提是你的專案與工具鏈在 WSL 側可用。

​
2.4 模型選擇

Teammate 預設不繼承 lead 的 /model 選擇。要設預設 teammate model：在 Claude Code 內跑 /config，選 Default teammate model。可選「Default（leader’s model）」讓 teammate 跟 lead 用同模型 [1]。

​
3. 協作模式

​
3.1 主從編排（Orchestrator-Worker）

一個主 agent 拆解任務後依序或並行 spawn 多個 Sub Agent，收集結論後整合。Sub Agent 互不知曉彼此存在。 
Lead: 把這個 PR 拆三塊分析
  ├─ spawn Subagent A (security)
  ├─ spawn Subagent B (performance)
  └─ spawn Subagent C (style)
  收集三份結論，整合成單一回應
對應 Sub Agent 機制，Agent Teams 也支援此模式但更貴。什麼時候用 Sub Agent 即可：每個 worker 是獨立、唯讀、結論能合併的；worker 之間不需對話。

​
3.2 平行獨立分工

多個 Sub Agent 同時處理不重疊的子任務（各自操作不同檔案或模組），主線最後 merge 結論。最常見的多代理模式，實作最簡單。 對應 Sub Agent 機制。Agent Teams 也支援，但同樣是不必要的複雜度。判斷：worker 之間不需對話、結論可合併 → Sub Agent 就夠。

​
3.3 Agent 間訊息往返（Peer Messaging）

Agent Teams 之間透過 mailbox 傳遞訊息、協商狀態。適合流程需要多輪反饋的場景：
  • reviewer 把意見傳回 writer，writer 修改後再傳回 reviewer。
  • 多個 investigator 各自提出假說，互相挑戰，達成共識。
  • 平行探索的多個角度，最後由 lead 整合成單一結論。
三種模式的選擇範例情境 1：code review 三個 reviewer（security / performance / test coverage）各自看同一 PR，回傳結論。→ Sub Agent 就夠（結論合併、不需對話）。情境 2：研究某個開源專案是否值得採用 一個研究 owner agent 派三個 Sub Agent 分頭看「程式碼品質」「社群活躍度」「授權與維護狀況」。三份結論合併出單一建議。→ Sub Agent 就夠。情境 3：bug 調查，root cause 不明 spawn 5 個 teammate 各自提出一個假說、互相挑戰、留下任何撐過挑戰的證據。→ Agent Teams 才有價值（需要訊息往返、辯論結構）。情境 4：writer + reviewer 持續迭代文件草稿 writer 起草、reviewer 給意見、writer 修、reviewer 再看，來回多輪直到收斂。→ Agent Teams（Sub Agent 一次就消滅，無法多輪對話）。

​
4. 相互獨立作業

​
4.1 何時讓 agent 互不干擾

子任務之間沒有共享可變狀態（各自讀不同資料、寫不同檔案）→ 平行獨立最省事，無需同步機制。 對應實作：每個 Sub Agent / Teammate 工作在不同 worktree。Git worktree 是物理隔離手段（見 04-5）： 
# 為每個 worker 建獨立 worktree
git worktree add ../agent-A -b agent-A-branch
git worktree add ../agent-B -b agent-B-branch

​
4.2 何時需要共享狀態

任務 B 的輸入依賴任務 A 的輸出 → 改用順序編排（A 跑完才 B 跑）或 Agent Teams 訊息往返，不要用平行。 平行分工對依賴關係特別脆弱：A 與 B 都被派去「讀同一個檔、修改不同段落」，最後合併時衝突。事先盤點依賴：若兩任務共享可變狀態，要嘛順序跑、要嘛 Agent Teams 互相協調。

​
4.3 用 TeammateIdle / TaskCreated / TaskCompleted hooks 強化流程

Agent Teams 提供三個專屬 hook 事件點 [1, 見 04-6 Hooks]：
  • TeammateIdle：teammate 即將進入 idle。exit 2 給回饋讓它繼續工作。
  • TaskCreated：task 正在被建立。exit 2 阻擋建立。
  • TaskCompleted：task 正在被標記完成。exit 2 阻擋完成並給回饋。
這三個事件是「teammate 協作品質閘門」的位置：teammate 寫完程式碼、沒跑測試就 idle？用 TeammateIdle hook 擋下。teammate 標記一個 task 為完成、但 commit message 沒遵守團隊慣例？用 TaskCompleted hook 退件。 
{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-tests.sh"
          }
        ]
      }
    ]
  }
}

​
5. 成本與複雜度

​
5.1 不為平行而平行的判準

平行新增額外 context 成本與協調複雜度。若子任務彼此依賴、或整合結論的複雜度超過拆解的收益，不如線性跑。 成本評估三題：
  1. 子任務間是否真正正交？ 共用輸入、互相讀寫、共享狀態 → 不正交，平行反而慢。
  2. 整合結論的難度是否可控？ 若三份結論互相矛盾、需大量二次協調 → 拆解的收益不見了。
  3. 平行帶來的加速是否抵消額外 token 費用？ 5 個 Haiku worker vs 1 個 Sonnet 跑完：5 個 worker 燒 5× context，加速 5× 是上限。真實加速往往只有 2-3×（受通訊、同步、idle 時間影響）。

​
5.2 模型選型

Worker Agent 盡量用較便宜的模型（Haiku）；只有主 Orchestrator / Lead 需要推理能力時才用 Sonnet / Opus（參見 04-5）。 Agent Teams 預設不繼承 lead 模型（[1] 第 2.4 節）；明確指定才能省成本： 
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.
或用 /config 設 default teammate model 為 Haiku 系列。

​
5.3 已知限制

Agent Teams 為實驗性功能，官方明示的限制 [1]：
  • in-process 模式下 resume 不還原 teammates。
  • task 狀態可能 lag。
  • shutdown 可能慢（teammate 跑完當前 tool call 才停）。
  • 一個 lead 只能管一個 team。
  • 無巢狀。
  • lead 固定、不能轉移。
  • 權限模式在 spawn 時決定，啟動後才能改。
  • split-pane 模式需 tmux / iTerm2。
CLAUDE.md 對 teammate 同樣生效官方明示 teammates 會讀 CLAUDE.md，作為專案級指引傳遞給所有 teammate [1]。這是規範 teammate 行為最直接的方式。把跨 teammate 通用的規範寫進 CLAUDE.md，不要依賴 lead 每次都交代。

​
6. 工具對照

概念Anthropic Claude（主範本）OpenAIGoogleGitHub CopilotCursor（短提）
一次性子代理Sub Agent（Agent(<name>) 工具）[04-5]設定式 [需確認原始出處]設定式 [需確認原始出處]設定式 [需確認原始出處]設定式 [需確認原始出處]
持續 / 可定址代理Agent Teams（v2.1.32+，實驗性）[1]Swarm / Assistants 概念類似 [需確認原始出處]設定式 [需確認原始出處]設定式 [需確認原始出處]設定式 [需確認原始出處]
共享 task list是（~/.claude/tasks/<team>/）[1]設定式設定式設定式設定式
Agent 間訊息是（mailbox + SendMessage）[1]設定式設定式設定式設定式
Teammate hook 事件TeammateIdle、TaskCreated、TaskCompleted [1, 04-6]不適用不適用不適用不適用
顯示模式in-process / split-pane（tmux / iTerm2）[1]設定式設定式設定式設定式
物理隔離手段isolation: worktree（[04-5]）環境層環境層環境層環境層
命名與邊界
  • Agent Teams（v2.1.32+） 為實驗性功能，預設關閉；以 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 啟用 [1]。
  • OpenAI、GitHub Copilot、Cursor 對多代理的具體機制以各家當前官方文件為準；上表「需確認原始出處」項目需查證。
  • Cursor 為第三方 IDE（Anysphere），本 Playbook 僅短提一欄。

​
動手做

1

三種模式各跑一次（20 分鐘）

主從編排（Sub Agent）：在當前專案下用三個 Sub Agent 平行做 security / performance / test coverage 三個角度的 review，觀察主線整合結論的成本。平行獨立分工（Sub Agent）：讓三個 Sub Agent 各自重構三個不同模組，觀察 worktree 隔離是否需要。訊息往返（Agent Teams，需先啟用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1）：建一個 3 個 teammate 的 team 對某個不熟悉的 bug 提出假說、互相挑戰。觀察 token 成本是否明顯高於 Sub Agent 模式。
2

加 hook 強化流程（10 分鐘）

在 .claude/settings.json 加 TeammateIdle hook，跑 /teammateMode 切到 tmux 模式（或維持 in-process），觀察 hook 是否觸發。

​
常見誤區

反模式清單
  • 把有依賴關係的子任務設計成平行分工：整合時需要大量二次協調，反而比線性慢。先用 01-5 Workflow Engineering 釐清誰依賴誰。
  • Agent Teams 的訊息格式沒有定義終止條件：造成無窮訊息往返或靜默卡死。每個訊息交換都有明確 exit condition（accept / reject / escalate）。
  • 所有 Agent 都用最強模型：忽略 worker 任務用 Haiku 即可的事實，成本失控。Worker 用 Haiku、Lead 用 Sonnet/Opus。
  • 把 Agent Teams 當 Thread 來用：Agent Teams 是完整 Claude Code 實例，有完整 context、完整工具、完整權限，不是「便宜的 Sub Agent」。預期它吃 token 的量級與一個獨立 session 相同。
  • 忘了 CLAUDE.md 對 teammate 生效：teammate 不繼承 lead 的對話歷史，但會讀專案的 CLAUDE.md [1]。把跨 teammate 通用的規範寫進 CLAUDE.md，不要依賴 lead 每次都交代。
  • 用 Agent Teams 跑小任務：一個 5 行的 grep 用 Sub Agent 即可，team 是為需要協作的多輪工作設計的。3 個 teammate 起步是過度工程化 [1]。

​
自我檢核

通過本單元的標準
  1. 你能用一張表說出 Sub Agent 與 Agent Teams 在生命週期、可定址性、通訊方式、Token 成本四個維度的差異嗎？
  2. 你能判斷下面三個任務各該用哪一個嗎？
    • 重構三個不同模組（互不依賴）
    • 對某個 bug 提出多個互相挑戰的假說
    • 跨 5 個檔案的功能新增（5 個小任務、每個都自己完整）
  3. 你最近一個多代理設計，子任務之間是真正正交的嗎？還是只是「感覺應該平行」？
  4. 你的 CLAUDE.md 有沒有寫明「哪些任務走 Sub Agent、哪些走 Agent Teams」的判準？

​
來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。
  • [1] Anthropic, “Orchestrate teams of Claude Code sessions,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/agent-teams （截至 2026-06；v2.1.32+ 啟用、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1、mailbox、shared task list、teammate hook 事件、display modes、已知限制）
  • [2] Anthropic, “Create custom subagents,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/sub-agents （截至 2026-06；Subagent 完整 frontmatter、isolation: worktree、skills 預載、Task → Agent 改命名 v2.1.63）
  • [3] Anthropic, “Hooks,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/hooks （截至 2026-06；TeammateIdle、TaskCreated、TaskCompleted 事件、exit 2 攔截語義）
  • [4] psmux, “psmux: native terminal multiplexer for Windows,” GitHub, 2026. [Online]. Available: https://github.com/psmux/psmux （截至 2026-06；Rust 單一二進位、相容 .tmux.conf、Windows native 不需 WSL/Cygwin；在 psmux session 內啟動 Claude Code 時 teammate 自動進 pane；版本 0.1.x，屬新專案）