Claude Code 多 Agent 協作：Subagents 和 Agent Teams 怎麼選

在 Claude Code 裡，和多 Agent 協作最容易混淆的兩個概念，就是 Subagents 和 Agent Teams。它們看起來都像是「開幾個 Agent 一起做事」，但定位其實不一樣。簡單說，前者更適合把獨立任務分出去做，後者更適合讓多個 Agent 圍繞同一件事持續協作、彼此驗證。

如果你之前用過 Skill，也可以先這樣理解：

Skill 負責定義流程和規則
Subagent 或 Agent teammate 負責實際執行任務

所以真正的問題不是哪個「更高級」，而是你要處理的是哪一類協作問題。

Subagents：把支線任務分出去

Subagents 更像是在目前會話裡臨時派出去的分身。每個分身都有自己的上下文視窗，做完之後只把結果摘要帶回來，主對話不會被大量中間輸出塞滿。

這類能力有幾個很直接的優點：

主線對話更乾淨，不容易被測試日誌、搜尋結果或長輸出污染
可以把彼此獨立的研究或執行任務並行化
很適合「把結果帶回來就好」的任務

原文提到，Claude Code 內建了三類 Subagent：

Explore：唯讀，適合快速搜尋程式碼庫
Plan：唯讀，適合在 plan mode 裡於背景收集資訊
General-purpose：可讀可寫，適合同時探索與修改的任務

自訂 Subagent

如果內建能力不夠，可以自己定義一個 Subagent。做法不複雜，本質上就是寫一個 Markdown 檔案：

.claude/agents/：只在目前專案生效
~/.claude/agents/：對所有專案生效

檔案格式類似這樣：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

這裡最關鍵的是 description。Claude 會根據這段描述判斷什麼時候該呼叫這個 Subagent，所以寫得越精準，觸發通常越準。

另外幾個常見設定欄位也很實用：

tools：限制它可以使用哪些工具
model：決定使用 sonnet、opus、haiku 或 inherit
permissionMode：控制編輯權限與權限提示行為
memory：給 Subagent 一個跨對話記憶目錄

如果只是暫時要用一次，也可以直接透過 CLI 注入：

1
2
3
4
5
6
7
8


claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Subagents 適合什麼場景

Subagents 最適合的，通常是這幾類任務：

跑測試並只回傳失敗摘要，而不是把幾千行日誌全塞回主會話
並行調查幾個互不依賴的模組
把「找問題」和「修問題」拆成簡單的流水線

例如：

1

Research the authentication, database, and API modules in parallel using separate subagents

1

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

但如果任務需要頻繁來回調整、不同階段共享大量上下文，或者改動高度集中在一兩個檔案裡，那麼直接在主對話中處理，往往比另外派一個 Subagent 更省事。

Agent Teams：多個獨立會話一起協作

Agent Teams 是另一個層級的能力。它不是在同一個會話裡派出分身，而是啟動多個彼此獨立的 Claude Code 實例，讓它們圍繞共享任務清單協作，還可以彼此直接傳訊。

這也讓它更像是一個真正的小團隊，而不只是「把支線任務分出去」。

原文提到，這項功能目前仍然是實驗功能，需要先開啟：

1
2
3
4
5


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

把它加到 settings.json 後，就可以讓 Claude 依照你的需求組成一個 team。比如：

1
2
3


I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

Agent Teams 的組成

一個 Agent Team 主要由三部分組成：

Team lead：你目前使用的主會話，負責組隊、分派與彙總
Teammates：多個彼此獨立的 Claude Code 實例
Task list 和 Mailbox：共享任務清單與訊息通道

和 Subagents 最大的差別在於，teammates 之間可以直接溝通，不需要每次都透過 lead 中轉。任務狀態通常會在 pending、in progress、completed 之間流轉，而成員完成一項任務後，也可以繼續認領下一項。

Agent Teams 適合什麼場景

當任務需要多角度討論、互相挑戰結論，或者拆成多個模組並行推進時，Agent Teams 會更合適。

原文舉了幾個很典型的場景：

多位 reviewer 並行審查同一個 PR，但各自關注不同面向
多個 Agent 針對同一個 bug 提出不同假設，並互相反駁
前端、後端、測試分別推進不同模組

例如並行程式碼審查：

1
2
3
4
5


Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

再比如辯論式偵錯：

1
2
3
4


Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

這類任務的共同點是：你不是只要一個答案，而是需要多個 Agent 彼此交換判斷、質疑假設，最後收斂出更可靠的結論。

兩者怎麼選

如果想快速區分，可以直接記這條：

做完把結果帶回來，用 Subagents
需要討論與交叉驗證，用 Agent Teams

再展開一點，主要差異可以從這幾個面向來看：

通訊方式：Subagents 主要把結果回報給主會話；Agent Teams 的成員之間可以直接互相溝通
協調模式：Subagents 更依賴主對話統一調度；Agent Teams 有共享任務清單，成員可以自行認領
Token 成本：Subagents 較省；Agent Teams 較高，因為每個 teammate 都是獨立實例
適用任務：Subagents 更適合獨立、結果導向的工作；Agent Teams 更適合需要討論與交叉驗證的工作

使用時要注意什麼

Agent Teams 雖然更強，但不代表每個任務都值得直接開 team。原文特別提醒了幾個實際問題：

token 消耗明顯更高
若多個 teammate 同時編輯同一個檔案，很容易互相覆蓋
teammate 太多會增加協調成本，不一定帶來更好效果

因此，通常比較穩妥的做法是：

先從 3 到 5 個 teammate 開始
依模組或檔案拆任務，避免寫入衝突
如果 lead 太早接手了 teammate 的工作，要明確要求它先等隊友完成

另外，目前的實驗功能也還有一些限制，例如：

不支援 /resume 和 /rewind 恢復 in-process teammates
任務狀態有時會延遲，需要手動提醒更新
一個 lead 一次只能管理一個 team
teammate 不能再派出子 team

簡單結論

這兩種能力並不是互相替代，而是分別解決不同的協作問題。

如果你的需求是「把支線任務並行做掉，保持主上下文乾淨」，那就先用 Subagents。如果你的需求是「讓幾個 Agent 像小團隊一樣協作、討論、交叉驗證」，那麼 Agent Teams 會更適合。

實際拿一個任務試一次，通常很快就能感受到差別：一個強調上下文隔離與結果回收，另一個強調多視角協作與持續互動。