Claude Code 平行工作：worktree、代理與 Workflows

平行運用代理的實用資料：Ailoot 文件。

本指南整理了實務經驗，以及各種工具的適用情境。內容包括 Claude Code 的四種官方原語、工具適用情境一覽，以及協助 vibe coder 判斷實際需要多少平行代理的反炒作架構。所有數字和引言都連結至 Anthropic 的一手資料。

Claude Code 的多代理是什麼？為什麼不是「1000 個代理」？#

多代理架構是指把一項任務拆成數個獨立的工作流程，各自處理一部分並回傳結果。最簡單的例子：你在一個 Claude Code 視窗寫前端，在同一台電腦的另一個視窗寫後端，兩者共用同一個 git 儲存庫。這已經是多代理，即使稱之為「編排」也未免太誇張。

更複雜一點的架構：在同一個 Claude Code 工作階段中，你啟動五個不同角色的 subagents（前端開發者、後端開發者、安全審查者、測試者、文件撰寫者），每個代理完成自己的部分，再把結果回傳到共用對話。這是同一種多代理做法，只是控制點只有一個。

再複雜一些：你告訴 Claude：「每週對我專案中的 500 個檔案做一次安全稽核」，接著它會撰寫 JavaScript 編排指令碼。執行環境在背景啟動數十個代理，各自稽核自己的部分，再由獨立代理互相檢查彼此的發現，最後回傳一份報告。這就是 Dynamic Workflows，Anthropic 於 2026 年 5 月 28 日推出的功能。功能詳解請見Dynamic Workflows 專題指南。

這三種情境的差別不在代理數量，而在於由誰決定下一個代理要做什麼。第一種情境由你決定；第二種由 Claude 隨著對話進行而決定；第三種則由 Claude 撰寫的 JavaScript 指令碼決定。

順帶一提，「1000 個代理」是真實數字，是 Claude Code 中單一 Dynamic Workflow 的上限。Anthropic 官方文件指出：

換句話說，這是防止行為失控的技術安全措施，不是建議的工作量。實務上，95% 的任務用 2～8 個平行工作流程就能完成。如果你打算用更多，先問問自己：它們各自要做什麼？

Claude Code 的 4 種原語：subagents、skills、agent teams、workflows#

Claude Code 提供四種官方原語，將一項任務分配給多個代理。Anthropic 在 Dynamic Workflows 文件中整理了比較表。以下以白話說明：

這些原語各自解決不同問題。Subagents 適合在單一任務中委派 2～3 項檢查。當你已有現成指示要 Claude 遵循（例如「使用這份檢查清單進行 PR 審查」）時，適合使用 skills。當產品的幾個部分分別在不同視窗中開發，而且需要一位協調者時，適合使用 agent teams。當任務大到超出單一上下文視窗時，適合使用 workflows。

詳細介紹請參閱 Claude Code Subagents 2026 指南。判斷「特定任務該用什麼」的決策樹，請見 Skills、Subagents、MCP、Plugins 指南。本指南則說明如何以 git worktree 為基礎，組成多代理架構。

層級 1：同一個工作階段中的 subagents——最簡單的起點#

Subagent 是拆分任務最簡單的方法。主要對話負責協調；主要代理會隨著工作進展，啟動臨時工作者。

文中所述專案的一個具體例子：指南初稿完成後，審查會這樣安排：Claude 收到以下要求：「平行啟動六個 subagents——第一個檢查 AI 特徵用語，第二個檢查法律詞彙，第三個檢查語氣與風格，第四個使用 WebFetch 查核事實，第五個審查 SEO 結構，第六個檢查交叉連結是否正確。」每個代理回傳報告後，再套用修改。

技術上，這是透過 .claude/agents/[subagent-name].md 檔案來完成，檔案中會描述角色與工具。呼叫則是在主要對話中透過 Agent 工具執行。Claude 會決定何時把要求交給 subagent。

適用情境。 對同一份成果物（程式碼、文字、設計）進行 3～7 項平行檢查。每項檢查彼此獨立，結果也放得進主要上下文視窗。

容易失效的情境。 如果有 50 個以上的檔案，或每項檢查都需要自己的 50K token 上下文，主要視窗就會塞滿。此時需要 workflows 或 agent teams。

主要風險。 每個 subagent 都會個別消耗 token。如果你在一個有 200 個檔案的專案中啟動六個代理，而每個代理都重新讀取全部 200 個檔案，費用會變成 6 倍。因此，你必須明確指定 subagent 要檢查哪些檔案。詳情請見 Claude Code 的 token 消耗在哪裡指南。

層級 2：git worktree——隔離平行工作階段之間的檔案#

當 subagents 不夠用，而你需要在不同終端機中執行兩個完整的 Claude Code 執行個體來處理同一個儲存庫時，典型問題就會出現。它們開始編輯同一個檔案，一個先存檔，另一個的內容就把它覆蓋了。上週有位客戶告訴支援團隊：「5 個同時互相覆蓋。」

解決方法是 git worktree。這是 git 內建功能，可讓同一個儲存庫擁有多個工作副本，各自使用不同分支，同時共用同一個 .git 儲存庫。來源只有一份，磁碟上有不同目錄，各自的檔案不會重疊。機制詳情請見 Claude Code 中的 Git worktree 指南。

五分鐘快速設定的指令：

# 從主要專案目錄開始
cd ~/projects/my-app

# 為 feature/auth 建立 worktree
git worktree add ../my-app-auth feature/auth

# 為 feature/billing 建立 worktree
git worktree add ../my-app-billing feature/billing

# 開啟兩個終端機視窗
cd ~/projects/my-app-auth && claude   # 第一個 Claude Code
cd ~/projects/my-app-billing && claude # 第二個 Claude Code

每個副本都在自己的分支上。每個 Claude Code 執行個體只會寫入自己的目錄。任務完成後，從該分支執行 git push，然後執行 git worktree remove ../my-app-auth。

需要知道的事。 Worktree 不會複製 node_modules、.venv 或其他列在 .gitignore 中的檔案。如果每個分支需要各自獨立的依賴項（例如不同版本的程式庫），請在執行 worktree add 後，到新目錄中另外執行 npm install。

每人可用多少 worktrees。 根據 2026 年的團隊調查，每位開發者平行使用 worktree 的實際上限是 4～8 個。限制因素不是 Claude，而是人類檢查並接受結果的能力。如果有 10 個 worktrees，它們就會排隊等候審查。

文中描述的實務通常使用 2～3 個平行 worktrees：一個主要 worktree 用於目前工作，一個備用 worktree 處理緊急 hotfix，另一個用於實驗（測試你不確定的新功能）。不需要更多。

層級 3：agent teams——多個視窗，一位主要代理負責帶領#

Agent teams 是相對較新的原語。概念是：一位主要代理以任務清單保管共用計畫，數個分別位於不同視窗的同儕工作階段，則各自接下主要代理分派的任務。所有代理都使用同一個檔案系統，因此可以看到彼此的中間產物。

如果一項任務可拆成 3～5 個大型工作流程，而且每個流程都要花上數小時，這種做法就很實用（例如移植大型模組、重寫子系統、進行完整安全稽核）。這時，主代理將計畫放在 worktree 外的單一絕對路徑。工作者讀該路徑並回報結果，只有主代理更新狀態，避免競爭寫入協調檔。

技術上，agent teams 是多個透過 git worktree 執行、並共用一個規劃點的視窗。實務上，80% 的人會依照上述 worktree 做法手動管理 agent teams，不會使用專門的「teams framework」。這樣完全沒問題。

如果你不確定自己是否需要框架，幾乎可以肯定你不需要。使用手動 worktree，並在主要目錄中安排一位主要代理就好。

層級 4：Dynamic Workflows——Claude 撰寫 JS 編排指令碼#

以上三個層次都把計畫留在對話中：在主要代理腦中，或在主要代理的任務清單中。Dynamic Workflows 則把計畫放進程式碼。Claude 以 JavaScript 指令碼表示任務，執行環境在隔離環境中執行指令碼，中間結果會存放在指令碼變數裡，而不是上下文中；代理在背景工作時，工作階段仍能保持回應。

官方文件中的具體例子如下。你說：

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude 會撰寫一個大致遵循以下邏輯的 JavaScript 指令碼：「取得 src/routes/ 中的所有檔案，把端點分成每組 30 個，再讓代理使用同一項檢查處理每組；接著啟動兩個獨立的 grader agents，檢查它們的發現，最後彙整成報告。」指令碼執行完後，你會得到一份結果表，以及一份確實需要檢查的端點清單。

適用情境：

• 對整個專案稽核同一類問題（安全性、型別、已棄用 API）。
• 大型移植（500 個以上的檔案都遵循同一項規則）。
• 需要從多個獨立角度查核的研究問題（Anthropic 透過內建的 /deep-research 指令執行此類工作）。

Dynamic Workflows、其限制以及 ultracode 運作方式的詳細說明，請見Claude Code 中的 Dynamic Workflows 專題指南。

不該使用的情況。 任務線性而且明確時，不要使用。像「完成這個元件」這種任務不需要 workflow。當一項任務拆成 10 個以上的獨立子任務，而且需要彼此交叉檢查時，才適合使用 workflow。

主要限制。 Workflow 消耗的 token 明顯多於一般工作階段。Anthropic 在文件中建議：

換句話說，第一次執行 workflow 時，先選一個目錄，不要直接涵蓋整個專案。先看看花了多少，再決定是否值得擴大範圍。

Outcomes：評估規準與獨立審查者#

多代理工作中最危險的事，是相信代理的輸出。每個代理回傳的文字看起來都像完成品。引言似乎正確，報告似乎完整，移植似乎完成。只有一個代理時，你還能自己檢查；有 10 個時，你就沒有時間檢查了。

Anthropic 透過 2026 年 5 月 6 日推出的 Managed Agents 功能 Outcomes 來解決這個問題。概念很簡單：在工作階段中加入第二個代理（評分代理），它唯一的工作就是依據嚴格的規準，檢查第一個代理的成果。

技術運作方式如下。你撰寫一份規準，也就是一份 Markdown 文件，詳列「完成」的定義、要查核哪些來源，以及要使用哪些標籤。平台會自動在全新的上下文視窗中建立評分代理。它只會收到規準和成果，不會收到其他內容。主要代理（撰寫者）每次嘗試後，評分代理都會重新閱讀結果，判定是否通過，或回傳尚未完成事項的逐項清單。

以下引自 Anthropic Cookbook：

實際成效數字：將 Outcomes 整合至 Claude Managed Agents 後，AI 公司 Harvey 的任務完成率提高約 6 倍。醫療文件服務商 Wisedocs 的文件審查時間則減少了 50%。這些數字來自官方功能公告。

對 vibe coder 而非企業來說，重要的是把 Outcomes 視為一種模式，而不只是特定功能。你可以在 .claude/agents/grader.md 中描述相同的評估標準，並要求主要代理在每次嘗試後執行，就能建立自己的 grader agent。這種方法適用於任何多代理架構，不限於 Managed Agents。

Cookbook 中撰寫規準的主要原則是指定可驗證的事項，而非籠統要求。不要只說「確認簡報涵蓋帳務」，而要說「開啟簡報，找到帳務相關段落，確認其中以 $ 金額或營收百分比標示數值」。第一種指示會讓評分代理略讀後打勾；第二種則會迫使它開啟文件並找出具體數字。

反模式：「50 個代理在做無意義的事」#

這是多代理工作的核心反模式。有人知道 Claude Code 可以同時執行 16 個代理，Dynamic Workflows 每次執行可以跑 1000 個代理，於是坐下來把它們全都啟動。結果是：零。token 消耗量是一般工作階段的 10 倍。

有個簡單的測試方法。拿一張紙，每個代理畫一個方框，並在每個框中寫下：

1. 它具體負責什麼（一句話）。
2. 它會接觸哪些檔案。
3. 它會回傳什麼。
4. 誰會檢查它的結果。

如果其中任何一項無法在 30 秒內回答，就不該使用那個代理。這個規則適用於所有層級：subagents、agent teams、Dynamic Workflows。

第二種反模式是把應該依序進行的工作平行執行。如果前端要先取得後端的 API schema 才能工作，就不要平行執行。先完成後端，再做前端。只有彼此獨立的任務才應平行執行。

第三種反模式是為了加快速度而使用多代理。這種做法只在一定範圍內有效。如果把一項任務拆成四個獨立工作流程，它們大約會在單一工作流程所需的時間內完成（再加上少量協調時間）。但如果在一台機器上跑 50 個工作流程，每個流程都會因為共用 CPU 而變慢。筆記型電腦的實際上限是同時執行 4～6 個 Claude Code 執行個體；超過之後就會開始降速。

費用多少？如何避免用光額度？#

2026 年 5～6 月，業界開始面對 AI 程式設計成本高於預期的現實。

一次一般 Claude Code 聊天工作階段的費用相對合理；若對整個儲存庫啟用 Dynamic Workflows，費用就會高出 20 倍。Anthropic 官方文件指出：

實務上該怎麼做？以下是文中實務經驗整理出的節省原則。

1. 精確指定每個代理要檢查的檔案。 不要說「檢查專案並找出問題」，而要說「檢查 src/auth/*.ts，確認每個函式都會驗證 userId」。第二種提示會明確指定你付費要求的工作。

2. 一律先在單一目錄中試跑 workflow。 不要涵蓋整個 src/，先從 src/auth/ 開始。如果你滿意結果，也了解費用，再擴大範圍。

3. 預設使用 /effort high，只有刻意決定時才使用 ultracode。 /effort ultracode 代表 xhigh 加上自動編排，費用非常高。只有任務真的需要多個平行工作流程時才使用。

4. 在可行的情況下，讓 subagents 使用較小的模型。 如果你用六個 subagents 審查一篇指南，負責檢查 AI 特徵的 QA 代理和交叉連結檢查器都不需要 Opus。Sonnet 就夠了。這可將用量減少 3～5 倍。

token 節省詳情請見 Claude Code 的 token 消耗在哪裡指南和如何避免用光 Claude Code 額度。

今天就開始：30 分鐘檢查清單#

1. 將 Claude Code 更新至 v2.1.154+

   這是支援 Dynamic Workflows 的最低版本。請在終端機執行 claude update。

2. 在 /config 中啟用 Dynamic Workflows

   Pro 方案預設為停用。開啟 /config，找到「Dynamic workflows」一列，並將其切換為開啟。Max、Team 和 Enterprise 方案則已經啟用。

3. 建立第一個 worktree

   在主要專案目錄中執行 git worktree add ../<project>-experiment <branch>。在該目錄中開啟第二個終端機視窗，然後執行 claude。

4. 新增共用任務清單

   使用所有 worktree 外的一個絕對路徑。每個 worktree 的 tasks.md 是不同檔，不會自動同步。主工作階段是唯一寫入者，工作者只讀並回報。

   建立一次協調目錄與清單：

       mkdir -p "$HOME/projects/my-app-coordination"
       printf '%s\n' '# Tasks' '- Auth: assigned to the auth worktree' '- Billing: assigned to the billing worktree' > "$HOME/projects/my-app-coordination/tasks.md"
   

   第一個終端機：

       cd "$HOME/projects/my-app-auth"
       printf 'Shared task list: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
       claude
   

   第二個終端機：

       cd "$HOME/projects/my-app-billing"
       printf 'Shared task list: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
       claude
   

   在兩工作階段提供上方印出的同一完整絕對路徑：「讀取共用任務清單，只處理獲派任務與檔案，不編輯清單；完成與阻礙回報給唯一更新清單的主工作階段。」先確認兩代理能讀取該確切檔案，若出現權限提示，應針對該路徑解決。清單只協調狀態，程式變更仍在獨立 worktree。

5. 先這樣工作一週

   不要馬上安裝 GUI 包裝工具。先用兩個 worktrees 手動工作一週。你會看出缺少什麼，然後再針對特定痛點選擇合適的工具。

6. 之後才啟用 `/effort ultracode`

   選一項任務，例如「找出 src/routes/ 中所有沒有驗證檢查的 API 端點」。啟用 /effort ultracode，觀察 Claude 撰寫的 workflow、費用，以及產生的結果。這就是你的第一個 Dynamic Workflow。

接下來可以探索：工作階段間的記憶、Code Review、Multi-Agent v2#

以下介紹 2026 年 5～6 月出現的功能，以及 Claude Code 多代理的發展方向。

搭配 Dreaming 的 Managed Agents。 於 2026 年 5 月 6 日在 Code with Claude 推出。一個排程執行的程序會在工作階段之間讀取代理過去的逐字稿，找出重複出現的模式，並更新其記憶。AI 法律公司 Harvey 的任務完成率在導入 Dreaming 後提高了 6 倍。目前仍處於研究預覽階段。

作為 Managed Agents 功能的 Outcomes。 如上所述。此功能可透過 Claude Agent SDK 使用，無法直接從 Claude Code CLI 呼叫。現在就可以手動使用 grader subagent，套用相同模式。

Claude Agent SDK 中的 Multi-Agent Orchestration v2。 由主要代理使用共用檔案系統，自行委派工作給 subagents。這是從「手動啟動 N 個 subagents」走向「描述任務後，由主要代理自行決定委派給誰以及怎麼委派」的一步。如果你才剛開始學 subagents，現在不用擔心 v2。先學會傳統模式——「一個主要代理 + 3～5 個各司其職的 subagents」——再於 3～6 個月後自然轉向 v2。

代理團隊執行 Code Review。 Anthropic 在 Code with Claude 宣布一項功能：開啟 PR 時自動執行程式碼審查。一組 AI 代理會平行檢查 diff、搜尋錯誤、彼此驗證發現，並依嚴重程度排序。目前 Team 和 Enterprise 可用，Pro 尚未提供。

Plugin Marketplace。 於 2026 年 5 月 23 日，在 v2.1.128-136 推出。部分市集外掛是現成的多代理架構（parallel-review、security-audit、migration-helper）。你可以透過 /plugin install <name>@claude-plugins-official 安裝，並查看其組成方式，這是學習撰寫自製外掛的好方法。

Claude Code 的多代理仍是一組成熟度各異的原語。Subagents 和 git worktree 穩定、經過驗證，而且能在各處運作。Agent teams 半自動、半手動。Dynamic Workflows 仍處於研究預覽階段，且快速變動。Managed Agents v2 則僅供企業使用。這代表未來一年，vibe coder 的最佳架構不會是最新版本，而是能滿足特定任務所需的最精簡架構。持續一個月的密集工作，只需要兩個 worktrees 和一個 grader subagent。等你開始感到受限時，再增加複雜度。

適合 vibe coding 的實用架構#

實用資料請見：Ailoot 文件。

更多資料與工具：Ailoot。