Claude Code多Agent並行指南：Agent Teams、Worktree與整合

Claude Code目前提供Subagents與實驗性的Agent Teams兩種平行工作方式：Subagent在獨立Context完成局部任務，結果回報主Session；Agent Teams則啟動多個獨立Claude Code實例，使用共享Task List、直接互相傳訊，並由Team Lead協調。多Agent只有在任務低耦合、輸出可獨立驗收、Review與CI有足夠吞吐時才會縮短交付週期。若多個Agent修改同一核心檔案、共享Schema仍在變動，並行只會增加衝突和重做。本文聚焦Agent Teams與並行治理；日常操作、工具鏈、額度和Ralph由其他四篇承接。

重點快讀

• Agent Teams屬實驗功能，預設停用，且有Session恢復、協調與關閉限制。
• 官方要求Claude Code v2.1.32或以上。
• 一個Team Lead負責建立團隊、分派工作與整合結果。
• Teammates是獨立Claude Code實例，可直接互相通信。
• Subagents成本較低，Agent Teams適合需要討論和自我協調的複雜任務。
• 每個程式工作使用獨立Worktree、Branch與檔案Owner。
• Agent完成只能進Review，通過全域測試後才算Integrated。

如何啟用Agent Teams

Agent Teams目前不是預設功能，需要在設定或環境中加入CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS，並確認Claude Code版本符合官方要求。

# 檢查版本
claude --version

# 啟用實驗功能
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

實驗功能不適合直接成為正式開發流程的唯一依賴。導入前應先測試Session恢復、任務取消、Teammate關閉和失敗後的Artifact保存。

Agent Team由哪些元件組成

Subagents和Agent Teams怎麼選

哪些任務適合Agent Teams

• 研究與Review：不同Teammate分析不同風險，再互相挑戰發現。
• 新模組：Frontend、Backend、Tests各自有清楚Owner。
• 競爭假設除錯：不同Agent同時驗證不同根因。
• 跨層功能：介面已固定，能分開實作不同層。
• 大型Code Review：安全、型別、測試與效能分開檢查。

哪些任務不適合並行

• 工作具有嚴格前後順序。
• 多個Agent會修改同一核心檔案。
• 公共API、Schema或權限模型尚未確定。
• Database Migration具有順序與不可逆風險。
• Production Incident需要單一指揮。
• Review Queue與CI已經塞滿。
• 產品、法律或架構仍需人類決策。

先建立Dependency DAG

tasks:
  schema:
    id: T01
    dependencies: []
  backend:
    id: T02
    dependencies: [T01]
  frontend:
    id: T03
    dependencies: [T01]
  tests:
    id: T04
    dependencies: [T01]
  integration:
    id: T05
    dependencies: [T02, T03, T04]

沒有依賴的節點才能同時開始；Schema、權限和共享Contract位於關鍵路徑，應先由單一Owner固定。

每張Task Card需要什麼

• Goal：完成後新增的明確行為。
• Dependencies：必須先完成的Task與Artifact。
• Read Scope：允許讀取的Context。
• Write Scope：可以修改的路徑。
• Prohibited：不能碰的檔案、環境和外部Action。
• Contract：API、Schema、格式與版本。
• Acceptance：Tests、Screenshot或Review Rubric。
• Budget：Turn、時間、Token與工具。
• Handoff：完成、阻塞與整合格式。

Worktree如何隔離修改

每位Teammate應使用獨立Branch或Git Worktree，避免共享工作目錄和未提交狀態。

1. 從相同Base Commit建立Worktree。
2. 分配唯一模組或檔案Owner。
3. 禁止自行修改共享Contract。
4. 完成後提供Commit、Diff、Tests與Handoff。
5. 由Integration Owner按依賴順序合併。

官方Subagent也可使用isolation: worktree建立臨時Worktree；Agent Teams仍應自行建立清楚的Workspace和合併規則。

WIP上限怎麼設定

WIP上限不應等於能啟動多少Agent，而應取決於最慢的下游能力。

WIP上限 ≈ min(
  Agent執行容量,
  CI容量,
  Review吞吐,
  Integration吞吐
)

團隊每天只能Review三個Patch，同時啟動二十個Agent只會產生十七個等待成果和更高成本。

Review Queue需要哪些狀態

Teammate宣告完成只能進入Review，不能直接等同Accepted或Integrated。

Team Lead負責什麼

• 維護Goal、DAG、優先級與WIP。
• 分配Task、Context、Tools和Budget。
• 追蹤共享依賴與阻塞。
• 檢查Evidence與輸出格式。
• 處理重複、衝突和規格變更。
• 安排Integration順序。
• 決定何時停止並行或交給人類。

Integration Gate

1. 確認所有Task通過個別驗收。
2. 按DAG順序合併共享基礎與功能。
3. 解決Schema、Dependency與Config衝突。
4. 執行全域Test、Build和Security Scan。
5. 測試跨模組與端到端流程。
6. 確認Migration和Rollback。
7. 由具名Owner批准進入主線。

何時應停止並行

• 共享規格持續變動。
• 多個Teammate反覆修改同一區域。
• Review Queue持續增長。
• Integration時間超過節省時間。
• Token、Tool或CI接近上限。
• 出現Secrets、越權或不可逆動作。
• 需要人類產品或架構決策。

如何衡量並行是否有效

• Wall-clock Cycle Time。
• Accepted Task Rate。
• Review Queue Time。
• Conflict與Rework Rate。
• Human Review Time。
• Integration Failure Rate。
• Cost per Integrated Task。

五篇內容如何分工

• 操作指南：Session、Plan、權限、Git與交付。
• 工具鏈：Memory、Skills、Hooks、MCP與Subagents。
• 額度成本：訂閱、Credits與API。
• Ralph Loop：Stop Hook與迭代。
• 本篇：Agent Teams、Worktree、WIP、Review與整合。

讀者常問

Agent Teams是正式穩定功能嗎？

目前屬實驗功能，預設停用，並存在Session恢復、任務協調和關閉限制。

Subagent和Agent Team哪個比較省？

通常Subagent成本較低；Agent Teams的每位Teammate都是獨立Claude實例。

同一Repository能同時修改嗎？

可以，但應使用獨立Worktree、模組Owner與固定共享Contract。

Agent越多一定越快嗎？

不一定。Review、CI、依賴與Integration通常才是實際瓶頸。

官方資料

• Agent Teams
• Subagents
• Extend Claude Code

Claude Code多Agent並行的產能，來自可分割工作、清楚依賴和足夠驗收能力。Agent Teams能讓不同Claude實例直接協作，也會同步放大Token、衝突和整合成本；先控制WIP與Review，再增加Teammate，才會真正縮短交付週期。