Workflow 工具：腳本化的多代理編排

你將學到什麼

Dynamic workflow 是一份協調 subagents 的 JavaScript 腳本，並由專用 runtime 在背景執行控制流。當迴圈、條件分支或 fan-out 應該可讀、可重複，而不該只存在模型的對話 context 時，就適合使用它。

完成本課後，你會知道：

• 何時該用 workflow，而不是 subagent、skill 或 agent team
• 如何啟動、查看、核准、儲存並重跑 workflow
• meta、agent()、pipeline()、parallel()、phase() 與 args 的官方結構
• runtime 的真實限制與同 session resume 邊界
• 哪些 failure 與 budget 假設不應寫進腳本

選對協作層

機制	誰決定下一步？	最適用途
Subagent	Claude 每回合決定	少量委派工作，結果回到同一 context
Skill	Claude 依照儲存的指示	可重複的方法或領域流程
Agent team	Lead 監督長時間運作的 peers	需要共享 tasks 並互相傳訊的 teammates
Workflow	Script runtime	大型且可重複的迴圈、fan-out、分支與交叉檢查

Workflow 並非自動更好。單一查詢或高度耦合的修改，用一個 agent 開銷更低。只有當程式碼確實更適合管理 bookkeeping 時才使用 workflow。

Dynamic workflows 需要 Claude Code 2.1.154 以上，適用於付費方案與支援的 API／雲端 provider surface；Pro 使用者需在 /config 的 Dynamic workflows 項目開啟。

三種啟動方式

先試內建 workflow

/deep-research Node.js v20 到 v22 的 permission model 有哪些變化？

/deep-research 會扇出研究、交叉檢查 claims，最後回傳一份有引用的報告。

直接要求 workflow

use a workflow to audit every route handler under src/routes/ for missing authentication checks, then adversarially verify each finding

ultracode 關鍵字也是一次性明確觸發方式，不會更改 session 儲存的 effort level。

讓 ultracode 決定

/effort ultracode

這個 session 設定會結合 xhigh effort 與針對實質任務的自動 workflow 規劃。適用條件與範圍請見第 26 堂課。

儲存後的腳本長什麼樣

一般由 Claude 撰寫腳本。小型已儲存 workflow 的官方結構如下：

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: {
    type: 'object',
    required: ['files'],
    properties: {
      files: { type: 'array', items: { type: 'string' } },
    },
  },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

腳本以 literal meta export 開頭，並使用支援 top-level await 的 plain JavaScript。

• agent() 啟動一個 subagent。
• pipeline() 對一組項目套用 stages。
• parallel() 並行執行彼此獨立的 functions，並等待整組完成。
• meta.phases 存在時，phase() 會在進度畫面中分組工作。
• args 是呼叫已儲存 workflow 時傳入的 structured input；若省略則為 undefined。

精確的 input/output types 應以 Agent SDK reference 為準。不要從範例自行推導 return、exception 或 in-script budget contract。

核准與權限

互動式執行開始前，Claude Code 可以顯示規劃的 phases，讓你：

• 只執行一次；
• 永遠允許本專案的該 workflow；
• 查看 raw script；或
• 取消。

實際 prompt 取決於 permission mode。Workflow agents 以 acceptEdits mode 執行，並繼承 session 的 tool allowlist。Allowlist 外的 shell、web 與 MCP calls 仍可能在執行中要求權限。Workflow 無法在中途停下來詢問一般業務問題；需要人類簽核時，應拆成兩個 workflows。

查看、暫停與儲存

執行 /workflows 可查看進行中與已完成的 runs。畫面會顯示 phases、agents、耗時與 token 使用量，也可暫停、resume、停止、重啟 agent 或儲存腳本。

儲存後會成為 slash command：

• .claude/workflows/：隨 repository 分享的 project workflow
• ~/.claude/workflows/：跨 projects 使用的 personal workflow

已儲存腳本透過 args 讀取呼叫輸入，因此同一套編排可處理不同 paths、issues 或研究問題，不需修改來源。

Runtime 邊界

官方限制很明確：

邊界	目前行為
Script 存取	不可直接讀寫檔案或執行 shell；由 agents 使用 tools
中途輸入	不接受一般 user input；只有 agent permission prompts 可暫停
並行數	最多 16 個 agents；CPU 受限時更少
Worker 總數	每次 run 最多 1,000 個 agents
Session 結束	下一個 session 會從頭啟動 workflow

Pause 與 resume 只在同一 Claude Code session 內有效。已完成的 agent() calls 可回傳 cached results；暫停時仍在執行的 agent 會重新開始。因此，把工作拆成較短的 fan-out，通常比單一超長 worker 更能保留進度。

成本與規模

Workflow 可能比單一 conversation 使用多得多的 tokens。大型執行前：

1. 先用一個 directory 或小樣本演練；
2. 在 /workflows 觀察 token 使用量；
3. 證據不再改善時停止；
4. 若希望 Claude 預設寫得更小，可在 /config 設定 workflow size guideline。

Size setting 是給 Claude 的建議，不是強制上限。自 2.1.203 起，超過 25 個排程 agents 或預估 150 萬 tokens 的 run 會顯示 Large workflow 警告。這個警告同樣只是 advisory；ultracode 開啟時不顯示，因為 session 已明確選擇大規模執行。

實務設計規則

• 只有真正獨立的工作才 fan out。
• 需要跨項目去重或排序時，等相關結果齊全再做。
• 要求 agents 回傳精簡、結構化的 evidence，而非完整 transcripts。
• 在任務中寫出 stop condition：檢查通過、連續兩輪無新結果，或不再有進度。
• 最終報告要記錄 sampling、跳過的工作與 unresolved claims。
• 需要人類決策時拆成不同 stages/runs。

核心洞見

Workflow 把協作狀態從 conversation 移進程式碼。 每個 agent 內仍由模型提供判斷，但迴圈、fan-out 與中間值變得可檢查、可重複。這讓編排容易稽核，同時不把未記載的內部行為誤當成 API 保證。

下一堂課

第 28 堂課把這些機制組成編排品質模式：獨立搜尋、對抗式驗證、明確停止與可稽核證據。

官方來源

• Dynamic workflows
• 各種 agent 機制的選擇
• Agent SDK Workflow tool types