Claude Code agent teams 和 subagent 有什麼不同：各自何時使用，以及如何建立團隊

Agent teams 和 subagent 的差別

兩者都在各自獨立的上下文視窗裡平行工作。差別在於由誰協調：使用 subagent 時，主 agent 統籌一切；在團隊裡，隊友從共用清單認領任務，並且互相溝通。

何時該用 agent teams（何時不該用）

• 研究與審查：隊友從不同角度檢視同一個問題，再互相質疑彼此的結論。
• 新模組或新功能：每位隊友負責獨立的一塊，例如前端、後端和測試。
• 用幾個互相競爭的假設來除錯：幾位隊友各自設法證明自己的理論，同時推翻其他人的。
• 不適合循序進行的工作、要修改同一批檔案的工作，或相依關係很多的任務：這些情況請用單一工作階段或 subagent。
• 不適合例行工作：每多一位活躍的隊友，token 用量就跟著增加。

如何建立一個 Claude Code agent team

1. 開啟 agent teams

   在環境變數中，或 settings.json 的 env 區塊中，把 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 設為 1。團隊只能在互動式工作階段中使用；使用 -p（以及 Agent SDK）時，Claude 不會產生隊友。

   // settings.json: agent teams are experimental and off by default
   {
     "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
   }
   
   // Optional: give each teammate its own split pane (tmux or iTerm2)
   {
     "teammateMode": "auto"
   }

2. 用白話描述團隊

   說清楚要幾位隊友、每位負責什麼。Claude 會建立共用任務清單、產生隊友，並在它們完成後彙整結論。

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

3. 選擇顯示模式

   預設是行程內（in-process）模式，任何終端機都能用：隊友會顯示在提示字元下方的面板中；用方向鍵和 Enter 開啟某位隊友並傳訊息給它，按 Ctrl+T 查看任務清單。分割窗格模式讓每位隊友有自己的窗格，需要 tmux，或安裝了 it2 CLI 的 iTerm2；把 teammateMode 設為 auto 或 tmux，或用 claude --teammate-mode auto 啟動。

4. 重複使用已定義好的角色

   請 Claude 產生一位「using the security-reviewer agent type」的隊友，就能重複使用 .claude/agents/ 裡的 subagent 定義，包含它的工具、模型和指示。

5. 隨時引導，最後關閉

   隨時查看隊友的進度、調整它們的方向；如果負責人開始自己做隊友的工作，就對它說「wait for your teammates」。收尾時，請負責人依名稱關閉某位隊友；工作階段結束時，團隊的目錄會被清除。

來源：Claude Code 文件，Agent teams（英文）

最佳做法與限制

• 先從 3–5 位隊友開始，每位大約 5–6 個任務；三位專注的隊友往往勝過五位各做各的。
• 給每位隊友分配不同的檔案：兩位隊友修改同一個檔案會互相覆蓋。
• 把任務細節寫進產生隊友的提示詞：隊友會載入 CLAUDE.md、MCP 伺服器和 skills，但看不到負責人的對話。
• 用 hooks 當品質關卡：TeammateIdle、TaskCreated 和 TaskCompleted 可以用結束代碼 2 把工作退回。
• 限制：每個工作階段只能有一個團隊，不能巢狀建立團隊，負責人無法更換，/resume 無法還原行程內的隊友，任務狀態也可能延遲。
• 分割窗格在 VS Code 整合式終端機、Windows Terminal 和 Ghostty 中無法使用；行程內模式到哪裡都能用。
• 開啟 agent teams 後，Claude 指名呼叫的 subagent 可能會以隊友身分啟動；想恢復一般的 subagent，就把這個變數設為 0。

Agent teams 與其他平行執行 Claude Code 的方式

Agent teams 是在一個工作階段裡拆分你正在盯著的一個任務。若是彼此獨立的任務，就在 git worktrees 裡開多個工作階段，或使用背景 agent；完整比較請看多個 Claude Code agent。想降低成本，請參考如何減少 Claude Code 的 token 用量。

一支工作階段結束後仍持續工作的團隊

agent team 只存在於一個工作階段裡，關掉就停止。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 工作階段變成有固定職位、目標和工作時間的 AI 員工：每位員工依心跳醒來，從共用看板接下一個 issue，需要你做決定時傳訊息給你。

1. 給每位員工一個職位

   軟體工程師、程式碼審查員、SEO 專員：就是你會產生成隊友的那些角色，只是會一直留著。

2. 大家在同一塊看板上工作

   issue 取代了工作階段裡的任務清單，而且重新啟動後、過了幾天幾週都還在。

3. 讓心跳啟動工作

   在工作時間內每 15、30 或 60 分鐘一次；了解什麼是 AI 員工。

Claude Code agent teams 常見問題