Claude Code Dynamic Workflows 教學|上百子代理怎麼用

文章屬性:教學實戰
適用系統:Claude Code CLI、桌面版、VS Code 與 JetBrains 擴充、非互動模式與 Agent SDK
難易度 / 耗時:★★☆ / 讀完約 12 分鐘,第一次試跑再抓 10 分鐘
核心結論:Dynamic Workflows(動態工作流)是讓 Claude 現寫一支 JavaScript 腳本,由獨立執行環境在背景調度數十到數百個平行子代理,跑完再把單一結果交回來。
適用對象:已在用 Claude Code 的付費方案使用者(Pro 需自己去 /config 開)

📌 快速答案

一句話答案:Claude Code Dynamic Workflows 是由 Claude 現寫一支 JavaScript 腳本、在背景調度數十到數百個平行子代理完成大型任務,所有付費方案皆可使用,Pro 方案需自行在 /config 開啟。

🧰 開始前的準備

系統需求:Claude Code CLI、桌面版、IDE 擴充、claude -p 非互動模式或 Agent SDK 皆支援。啟動時直接帶 claude --effort ultracode 需 v2.1.203 以上;規模建議功能(含 /config workflowSizeGuideline=small)需 v2.1.202 以上,而「把 workflowSizeGuideline 這個鍵寫進 settings 檔」以及預設值為 medium,則需 v2.1.219 以上(更早的版本預設是 unrestricted);/workflow-authoring 技能需 v2.1.248 以上。
權限需求:一般使用者即可。但組織管理員可在 managed settings 或 Claude Code 管理設定頁把整個功能關掉,關掉後你這邊完全叫不出來。
需要工具:Claude Code;內建的 /deep-research 工作流需要 WebSearch 工具可用。
預計耗時:開關確認 2 分鐘;第一次試跑視題目大小而定。
難度門檻:不需要自己寫 JavaScript——腳本是 Claude 寫的,你只要看得懂它要跑什麼、決定放不放行。

🔍 為什麼你需要這個?

如果你用 Claude Code 做過「把 500 個檔案從 JavaScript 遷到 TypeScript」或「把整個 repo 的路由掃一遍看哪裡漏了驗證」,大概都遇過同一件事:單一對話撐不住。子代理一個個派、結果一筆筆塞回 context,跑到一半視窗就滿了,而且中間出錯就得整輪重來。

動態工作流要解的就是這個。它把「計畫」從對話搬進一支腳本:Claude 依你的敘述寫出 orchestration script,由一個獨立的 runtime 在背景執行,中間結果留在腳本變數裡,不進 Claude 的 context——最後只有結論回到對話。官方在 2026 年 5 月 28 日的公告裡把它定位成「本來要用季來排的工作,現在幾天做完」,並已宣布正式全面開放(generally available)。

本文和多數功能介紹不同的地方有三個,先講在前面:第一,把官方那張「誰拿著計畫」的對照表講清楚——這是子代理、技能、代理團隊、工作流四者真正的分水嶺;第二,把官方文件裡明列的硬性上限與費用警示門檻整理出來,這是實際用起來最容易踩的雷;第三,腳本層有幾條反直覺的規則(時間函式會直接丟例外、不能 import()),不先知道會以為是 bug。

🛠️ 實戰步驟

步驟一:確認你的方案有沒有開

動態工作流在所有付費方案上都能用,差別只在預設值。官方部落格寫得比較細:Max、Team、Enterprise 方案以及透過 API 使用時預設開啟;Pro 方案要自己去 /config 裡的「Dynamic workflows」那一列打開。

平台方面,除了 Claude API,也支援 Amazon Bedrock、Google Cloud 的 Agent Platform 與 Microsoft Foundry。

反過來,想關掉有三個方式:

在 /config 把 Dynamic workflows 切成關閉(官方明載跨 session 保留)
在 ~/.claude/settings.json 設 "disableWorkflows": true(官方明載跨 session 保留)
設環境變數 CLAUDE_CODE_DISABLE_WORKFLOWS=1——官方寫的是「啟動時讀取,所以你設在哪裡就在哪裡生效」;會不會跨 session 留著,取決於你有沒有把它寫進持久化的環境設定

💡 為什麼要知道關法?關閉後不只是不能跑——內建的工作流指令、/workflow-authoring 技能都會一併消失,ultracode 也會從 /effort 選單裡拿掉。如果你在同事機器上看不到這些東西,先查是不是被組織的 managed settings 關了,不是版本問題。

步驟二:先跑內建的 `/deep-research` 看一次全貌

不必一開始就拿自己的專案下手。Claude Code 內建了一個叫 /deep-research 的工作流,專門用來跨多個來源調查一個問題,拿它試跑最快看懂整個流程長什麼樣:

/deep-research What changed in the Node.js permission model between v20 and v22?

它會把網路搜尋依不同角度散開、抓回來源互相交叉比對,最後給一份附引用的報告——沒通過交叉查核的主張會被濾掉;而當查核代理因為速率限制或 API 錯誤查不動時,那條主張會被列為「未經查核」,而不是直接當成「已被推翻」。這個區分很重要,實際讀報告時別把兩者看成同一件事。

/deep-research 只有你主動叫它才會跑,不會自己觸發。

步驟三:讓 Claude 為你自己的任務寫一支

有兩條路,差別在「這一次」還是「整個 session」:

(A)單次任務——在你的 prompt 裡帶上關鍵字 ultracode,或直接用中文/英文說「用 workflow 跑」,Claude 都會當成同一個 opt-in:

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

(B)整個 session——設定 /effort ultracode,或啟動時就帶 claude --effort ultracode。ultracode 等於把推理強度拉到 xhigh 再加上自動決定要不要用工作流,開著的時候 Claude 會替 session 內每一件像樣的任務規劃工作流,一個請求可能拆成前後好幾支(理解程式碼一支、動手改一支、驗證一支)。想回到日常工作,/effort high 切回去就好。

幾個容易卡住的細節:

按錯了想取消:macOS 按 Option+W、Windows 與 Linux 按 Alt+W 取消這次的關鍵字反白;或把游標移到反白詞後面按倒退鍵。想永久停用,/config 裡關掉 Ultracode keyword trigger。
舊版關鍵字不同:v2.1.160 之前的字面觸發詞是 workflow;用自然語言請求則新舊版都通。
關鍵字只認「你親手打的」:透過 -p 傳入的 prompt、Agent SDK 未標記為人類輸入的訊息、排程任務的 prompt、webhook 或 PR 留言轉進來的內容,都不會觸發工作流(v2.1.210 起收緊;在那之前上述路徑也會觸發)。這條對有在跑自動化排程的人特別重要——別以為在排程腳本裡寫 ultracode 就會生效。

步驟四:放行前先讀腳本,跑起來用 `/workflows` 盯

CLI 會先跳出這次要跑的階段清單,四個選項:Yes, run it、Yes, and don’t ask again(僅限具名的內建/已存/外掛工作流,臨時寫的腳本沒這選項)、View raw script、No。Ctrl+G 直接用你的編輯器打開腳本,Tab 可以在開跑前調整 prompt。桌面版則是一張批准卡,列出名稱、階段與用量提醒,按鈕是 Once / Always / Deny。

會不會跳這個確認,看你的權限模式:Auto 模式只在第一次問(開了 ultracode 則完全略過)、Manual 與 accept edits 每次都問、Bypass permissions 直接跑、claude -p 與 Agent SDK 不跳確認框而是走一般的權限評估。

跑起來之後 /workflows 開進度視圖,可以看到每個階段的代理數、token 總量與耗時。這幾個鍵記一下:

鍵	作用
`Enter` / `→`	進入階段、再進入單一代理看它的 prompt 與結果
`p`	暫停或恢復整個 run
`x`	停掉選中的代理;焦點在 run 上時停掉整個工作流
`r`	重啟選中的執行中代理
`s`	把這次的腳本存成指令

💡 為什麼要看腳本?因為子代理的工具呼叫走的是你原本的權限規則與沙箱,和 session 內任何一次工具呼叫沒有兩樣。關鍵字只決定 Claude 用什麼結構做事,不會放寬任何權限。長時間的 run 想少被打斷,做法是事先把代理會用到的工具加進 allow 規則,而不是關掉檢查。

步驟五:跑對了就存成自己的指令

某次 run 的成果符合預期,/workflows 選中它按 s,存檔對話框用 Tab 在兩個位置之間切:

.claude/workflows/(專案內,跟著 repo 走,團隊共用)
~/.claude/workflows/(家目錄,你自己每個專案都能用)

存完之後它就是 /<名稱>,和內建指令一起出現在 / 自動補完裡。兩邊同名時專案的優先。要跨團隊分發就包成外掛——腳本放在外掛根目錄的 workflows/,叫用時會加上命名空間,例如 acme-tools 外掛裡的 release-audit 就是 /acme-tools:release-audit。

存起來的工作流可以透過 args 參數吃輸入,腳本裡用同名的全域變數讀。所以「每次改腳本裡的清單」這種笨方法可以省了:

Run /triage-issues on issues 1024, 1025, and 1030

🔬 底層機制:為什麼要把計畫搬進 JavaScript

一句話:差別在誰拿著計畫。

用子代理、技能、代理團隊時,Claude 自己是調度者——它一輪一輪決定接下來派誰,而每一份結果都會落進某個 context 視窗。工作流則是把迴圈、分支與中間結果通通交給腳本保管,Claude 的 context 只留最後答案。

這個差別帶來的不只是「跑更多代理」,而是可重複的品質模式:腳本可以安排幾組獨立的代理互相對抗式覆核彼此的發現才准回報,或是從幾個角度各擬一版計畫再互相比較——這是單次通過拿不到的結果。想理解子代理這一層的基礎,可以先看站長先前寫的 Claude Skills 是什麼?Agent Skills 讓 AI 學會新技能的開放標準,技能與工作流在官方對照表裡正好是相鄰的兩格。

腳本本體是帶 top-level await 的普通 JavaScript,可用的積木不多但夠用:

agent() 派一個子代理
pipeline() 對清單裡每一項各派一個
parallel() 同時跑一組並等全部完成
phase() 把接下來的代理歸進進度視圖的同一個標題底下
log() 在階段上方印訊息
args 讀外部傳進來的輸入

有幾條規則第一次看會覺得莫名其妙,但都有理由:

Date.now()、Math.random()、無參數的 new Date() 會直接丟例外。 因為重新啟動的 run 必須重現一模一樣的 agent() 呼叫;要時間戳就從 args 傳進去。
腳本裡出現 import() 會在開跑前就失敗。 需要函式庫的工作交給代理去做,腳本只負責調度。
腳本本身碰不到檔案系統與 shell。 讀寫檔案、執行指令是代理的事。
中途不能插話。 只有代理的權限提示能讓 run 暫停;需要階段之間簽核,就把每個階段拆成獨立的工作流。

另外,agent() 在你中途停掉它、或它撞上無法恢復的 API 錯誤時會 resolve 成 null,而 pipeline() 會把這個 null 留在結果陣列裡——官方範例最後接 .filter(Boolean) 就是在丟掉這些空值,不是隨手寫的。

⚠️ 上限、警示與費用:最容易踩的一段

工作流最現實的問題是吃 token。官方兩份文件都特別提醒:一次 run 可能比在對話裡做同一件事用掉明顯更多用量,而且照樣計入方案的用量與速率限制。

runtime 端有幾個硬性上限,寫死在文件裡:

限制	數值
同時執行的代理數	最多 16(CPU 較少時更低,含在 CPU 受限的容器裡)
單次 run 的代理總數	1,000
單次 `parallel()` 或 `pipeline()` 的項目數	4,096,超過直接報錯
fan-out 時共用快取前綴的代理延後啟動	預設最多 5 秒

再來是警示與規模建議,這兩者常被搞混:

Large workflow 警告:當工作流排進超過 25 個代理,或預估 token 總量超過 150 萬,輸入框下方的任務列會出現警告。它只是提醒,不會暫停也不會限制 run。開了 ultracode 的 session 不會顯示這個警告,因為開 ultracode 本身就等於同意跑大的。
規模建議(size guideline):告訴 Claude 寫腳本時該瞄準幾個代理,unrestricted(不設)、small(少於 5)、medium(少於 15)、large(少於 50),預設是 medium。注意這是「建議」不是上限,prompt 要求的規模不同時仍會蓋過它;runtime 的硬上限則永遠有效。

三個省錢的具體做法:

先切小範圍試跑:一個目錄而不是整個 repo、一個窄問題而不是大哉問。/workflows 視圖會即時顯示每個代理的 token 用量,不對就當場停,通常不會丟掉已完成的工作。
開跑前確認 /model:工作流代理的模型挑選順序和子代理相同,沒有其他指定時就用 session 的模型。平常切小模型做雜事的人,開大 run 前記得看一眼。
描述任務時直接指定:請 Claude 在不需要最強模型的階段改用小模型。想全面壓低代理數,規模建議選 small。

還有一個容易被忽略的省錢機制:同一次 run 裡的代理可以互讀彼此的 prompt cache。條件是模型、努力等級、代理類型、工具、輸出 schema 與工作目錄都相同。所以 Claude Code 在 fan-out 時會故意壓住除了第一個以外的代理,等第一個開始回應再一起放行,讓它們讀到共用前綴而不是各自重算——這個壓住的時間上限由 CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS 控制,預設 5000 毫秒,設成 0 就取消。另外工作流代理的快取預設只留 5 分鐘,想拉到一小時要設 subagentPromptCacheTtl 為 1h,但 API 端一小時的快取寫入計費較高。

🔁 中斷之後會發生什麼事

進度是邊跑邊存的,所以被打斷的工作可以接著跑,不用從頭來。但「接著跑」的規則要看懂,不然會以為它在重工:

已完成的代理:回傳存下來的結果。但只要有某個代理的 prompt 跟上次不同(你改了腳本,或前面的代理回傳了不一樣的東西),從它開始往後的每一個代理都會重跑,包括原本已完成的。
停掉時還在跑的:從頭開始。停掉整個 run 不會把任何代理算成失敗。
失敗的:重跑,而且它之後啟動的所有代理也一起重跑。單獨選中某個代理按 x 停掉,算作失敗。

所以官方直接點出後果:A、B、C、D 依序啟動而 B 失敗時,重新啟動會從快取拿回 A,然後把 B、C、D 全部重跑一次。fan-out 中間掛一個,後面做完的也白做。

離開 session 的方式也有差:把 session 背景化,run 會在背景 session 裡照樣接續;開著代理視圖時退出 Claude Code,退出對話框會給你「Move to background and exit」,選它才會保住;選「Exit and stop tasks」或根本沒給這選項,run 就跟著 session 停掉。停掉之後那次的結果仍存在該 session 的目錄下,用 claude --resume 接回去還能重放,但開一個全新 session 就什麼都沒得放,只能整個重來。

💡 總結:什麼時候該用、什麼時候別用

站長我的判斷標準只有一條:任務是不是「一個代理裝不下」或「同一個步驟要跑很多次」。符合就用工作流,不符合就別用——因為它換來的規模是拿 token 買的。

適合的形狀,官方文件本身給了幾個很好用的樣板句,可以直接改字用:

同一個問題掃很多檔案:「用工作流稽核 src/routes/ 底下每一個路由處理器有沒有漏掉驗證,每個發現都要對抗式覆核過才回報」
修到檢查通過為止:「用工作流跑 npx tsc --noEmit,持續修錯到型別檢查過關,或連續兩輪沒有進展為止」
平行遷移:「用工作流把 src/components/ 底下每個元件從 JavaScript 遷到 TypeScript,每個檔案在自己的獨立副本裡處理」
各檔各派審查者、最後合成一份:「用工作流審查這個 PR 改到的每個檔案,再把各檔發現合併成一份排序過的摘要」

不適合的也很明確:需要中途下判斷再往下走的任務(工作流中途不能插話)、幾個檔案的小改,以及你其實只想要一次乾淨的問答。後者用一般對話就好,想順手做資料整理的話,Claude Code 資料視覺化教學那套外掛更輕;模型怎麼挑可參考 Claude Opus 5 是什麼?功能、價格與怎麼選。

最後給個誠實的提醒:本文所有版本號、上限數字與設定名稱,都是 2026-09-02 依 Anthropic 官方部落格與 Claude Code 官方文件查證的結果,不是站長實機壓測的數據。這類功能改版很快(光是關鍵字觸發規則就在 v2.1.160 與 v2.1.210 改過兩次),真的要跑大型任務前,務必先小範圍試一次確認行為與你讀到的一致。

❓ 常見問題

Q:Dynamic Workflows 和「代理團隊」到底差在哪?兩個聽起來都是很多代理在跑。

差在誰決定下一步。代理團隊由一個 lead agent 一輪一輪監督其他 session,中間結果放在共享的任務清單裡,規模是「幾個長時間執行的同儕」;工作流則是腳本自己拿著迴圈與分支,中間結果放在腳本變數,規模是單次數十到數百個代理。中斷行為也不同:代理團隊的隊友會繼續跑,工作流則是在同一個 session 內可續跑。

Q:我在排程任務的 prompt 裡寫 ultracode,為什麼沒反應?

這是設計如此。自 v2.1.210 起,關鍵字只在你親手輸入的 prompt 裡才算 opt-in——互動式提示、IDE 擴充面板、Remote Control 客戶端,或 Agent SDK 應用程式明確把輸入標記為人類輸入時才會觸發。排程任務的 prompt、-p 傳入的 prompt、webhook 與 PR 留言都不會。在那之前的版本這些路徑確實會觸發,所以看到舊教學說可以,先確認版本。

Q:一次 run 最多能派幾個代理?會不會失控?

單次 run 上限 1,000 個代理,同時執行最多 16 個(機器 CPU 少會更低)。單次 parallel() 或 pipeline() 的清單上限是 4,096 項,超過會直接報錯而不是默默截掉——官方對這個設計的說明是「無聲的上限會在不通知腳本的情況下丟掉一部分工作量」。這些硬上限也順帶限制了失控腳本的成本。

Q:存起來的工作流可以直接改嗎?

可以,直接編輯那支 .js,或請 Claude 幫你改。但改之前先跑 /workflow-authoring 這個內建技能載入腳本撰寫參考(需 v2.1.248 以上)。要在當前 session 生效,改完跑 /reload-skills 重讀工作流目錄再叫一次 /<名稱>。另外 export const meta 必須是檔案第一個敘述、而且是只含字面值的物件;裡面塞變數、函式呼叫或展開運算子,這個指令就會從 / 自動補完裡消失。

🔗 延伸閱讀

📎 參考資料來源

📖 第一級|廠商官方:

Introducing dynamic workflows in Claude Code — Claude by Anthropic — 2026-09-02 查證(原文日期 2026-05-28)
Orchestrate subagents at scale with dynamic workflows — Claude Code Docs — 2026-09-02 查證
Create custom subagents — Claude Code Docs — 2026-09-02 查證
Claude Code settings — Claude Code Docs — 2026-09-02 查證

⚠️ 本文核心事實以第一級為準。

📅 本文查證戳記:2026-09-02 依 Anthropic 官方部落格與 Claude Code 官方文件撰寫,證據等級 E3(非第一手實機測試)。
若你在後續版本遇到步驟失效,歡迎在留言區回報,站長會更新文章。