精選 workflow orchestration multi-agent claude-code agents

什麼是 Workflow？解析 Claude Code 的多代理編排

什麼是 Claude Code 的 Workflow？解析多代理編排：以可重複執行的 JavaScript 控制流程協調眾多子代理，並附完整實作範例。

2026年7月8日 • 11 分鐘閱讀 • 作者：Claude World

如果你在 2026 年看過 Claude Code 處理大型任務，你可能見過它宣告「啟動一個 12 個 agent 的 workflow」——接著 /workflows 指令即時顯示進度，數十個子代理（subagent）向外扇出、互相驗證、最後收斂出一個答案。新使用者每次都會問同樣兩個問題：什麼是 workflow？「編排（orchestration）」到底是什麼意思？

本文從零開始回答這兩個問題。不需要任何多代理的先備知識。

簡短版答案

**Workflow（工作流程）**是一段由 Claude Code 撰寫、由 harness（執行框架）執行的小型 JavaScript 程式。腳本的職責是協調：生成子代理、把它們的輸出互相串接、平行執行多件事、決定接下來發生什麼——用的是普通的迴圈與條件判斷，而不是模型的即興發揮。

**編排（orchestration）**就是字面上的意思：一份樂譜，許多樂手。

  • 樂譜是 workflow 腳本。它讓編排可以被閱讀與重新執行：哪些 agent 執行、以什麼順序、拿什麼輸入。Agent 的模型輸出依然不是確定性的。
  • 樂手是子代理。每一個都是完整的 Claude agent，擁有自己的上下文視窗（context window）與工具。它們在樂譜分配的段落內行使判斷——閱讀程式碼、權衡證據、撰寫分析。

這種分工正是整個概念的核心，值得背下來：

控制流程放在程式碼裡，判斷交給模型。

模型在任務進行中決定「我該不該再生成一個 reviewer？」是即興演出——有彈性，但無法重現、也難以控管預算。由腳本來決定——for 迴圈、if 判斷——就是編排。

從單一 Agent 到交響樂團

Workflow 不是憑空出現的。它是一段演進的第四步，你可以沿著 Claude Code 的歷史一路追溯：

Stage 1: Solo agent
  ┌─────────┐
  │ Claude  │  one context window does everything:
  └─────────┘  read, plan, edit, test

Stage 2: Subagent fan-out (Agent tool)
  ┌─────────┐
  │ Claude  │──→ agent: "search the codebase"
  │ (main)  │──→ agent: "read these 40 files"
  └─────────┘    results return to the parent only

Stage 3: Agent teams
  ┌─────────┐    ┌─────────┐
  │ agent A │←──→│ agent B │  named agents that persist,
  └─────────┘    └─────────┘  continued via SendMessage

Stage 4: Scripted workflows
  ┌────────────────────────────┐
  │  JavaScript orchestration  │
  │  loops · phases · fan-out  │
  └──┬──────┬──────┬──────┬────┘
   agent  agent  agent  agent   (repeatable score,
                                 judging musicians)

Stage 1 是每個人的起點：一個 agent、一個上下文視窗。在任務超出單一上下文能容納的範圍之前，它都夠用。

Stage 2 加入了 Agent tool：主 agent 把多檔案閱讀與搜尋委派給子代理，自己的上下文只保留結論——而不是整批檔案內容。子代理預設在背景執行，其最終訊息只回傳給呼叫者。（深入說明見 Session 4：子代理與上下文隔離。）

Stage 3 讓 agent 成為可持續合作的夥伴：子代理可以被賦予一個 name，父代理之後可以透過 SendMessage 以信箱（mailbox）的方式繼續與它協作——上下文完整保留——而不是每次重新開始。（見 Session 9：Agent Teams 與通訊。）

Stage 4——Fable 5 世代的 Workflow tool——改變的是由誰決定結構。在 Stage 2 和 3 中，主 agent 是一輪一輪即興委派。在 workflow 中，結構以程式碼寫下，因此可以檢視與重新執行。Runtime 在背景執行腳本；整個過程中 /workflows 都會顯示即時進度。

為什麼要用腳本？可重複執行為何重要

把協調搬進程式碼，不會讓模型答案變成確定性的；它讓計畫可以檢視與重新執行，這才是有用的邊界。

**1. 可重複的結構。**同一份已儲存腳本會保留階段、迴圈、分支與扇出形狀。Agent 回答仍可能不同，因此每次執行仍需驗證。

**2. 可續跑的執行。**你可以在同一個 Claude Code session 中暫停並續跑；已完成的 agent 會重用保存結果，暫停時仍在執行的 agent 則會重跑。離開 Claude Code 後，下一個 session 會重新開始 workflow。

**3. 受 runtime 限制的平行化。**Runtime 最多允許 16 個 agent 同時執行、單次共 1,000 個 agent。這些上限用來防止失控扇出，不代表大型 workflow 必然便宜或安全。

4. 可觀測成本，不是 token 硬上限。/workflows 會顯示逐 agent token 用量，也能停止執行。當排程超過 25 個 agent 或預估超過 150 萬 tokens 時，Claude Code 可以發出警告；/config 也有 size guideline。兩者都只是建議，官方 runtime 並未記載 +500k 硬上限或腳本層級 budget API。

溫和導覽：agent()、parallel()、pipeline()

你不需要完整的 API 就能掌握概念（深入探討見 Session 27：Workflow 工具）。三個基本元件就能撐起大多數 workflow：

  • agent(prompt, opts?)——生成一個子代理，取回它的最終文字。透過 opts.schema 傳入 JSON Schema，你拿到的會是一個經過驗證的物件——子代理會被強制經由結構化輸出工具作答，形狀不符時自動重試。逐 agent 的 model 與 effort（推理強度）選項，讓你把便宜的模型放在機械式工作上、把頂級模型放在判斷上。
  • parallel(thunks)——同時執行多件事，並等待全部完成（一道屏障，barrier）。拋出錯誤的 thunk 會 resolve 成 null 而不是讓整次執行崩潰，所以你可以用 .filter(Boolean) 過濾。
  • pipeline(items, stage1, stage2, ...)——每個項目獨立流過每一個階段，階段之間沒有屏障：項目 A 可以在第 3 階段，同時項目 B 還在第 1 階段。總耗時（wall-clock）就是最慢的單一項目走完全程的時間。

這裡是一個完整而簡單的 workflow——平行審查一批變更檔案，然後合併發現：

export const meta = {
  name: 'review-changes',
  description: 'Review changed files in parallel, then merge findings',
  phases: [{ title: 'Review' }, { title: 'Merge' }],
};

phase('Review');
const files = args.files; // passed in when the workflow is invoked

// Fan out: one reviewer per file, all running concurrently.
const reports = (await parallel(
  files.map((file) => () =>
    agent(`Read ${file} and report any correctness bugs you find.`, {
      label: `review ${file}`,
      phase: 'Review',
      model: 'haiku',   // cheap tier for mechanical per-file reading
      effort: 'low',
    })
  )
)).filter(Boolean); // a failed reviewer becomes null — drop it

phase('Merge');
log(`Collected ${reports.length} per-file reports.`);

// One high-effort agent merges and ranks everything.
await agent(
  `Merge these review reports. Deduplicate and rank by severity:\n\n` +
  reports.join('\n---\n'),
  { phase: 'Merge', effort: 'high' }
);

幾個值得注意的地方：

  • 腳本以 export const meta = ... 開頭——一個純字面值（不含變數、不含函式呼叫），宣告名稱、描述與階段。每個 phase() 呼叫都對應那裡宣告的一個標題，這正是即時進度畫面的資料來源。
  • args 是 workflow 取得參數化輸入的方式；log() 會寫下敘事行，供你在執行過程中閱讀。
  • 腳本本身沒有檔案系統存取權，也沒有 Node.js API——agent 才有工具；樂譜不碰樂器。
  • 合併步驟刻意利用了 parallel 的屏障：它需要每一份報告都到齊，才能跨報告去除重複。這正是經驗法則——只有當下一階段需要來自上一階段所有項目的跨項目上下文時，屏障才是合理的。不需要跨項目比較的逐項處理鏈，應該放進 pipeline，那裡什麼都不用等。

想留下來重複使用的 workflow 放在 .claude/workflows/，之後可以用名稱呼叫；一個 workflow 甚至可以透過 workflow() 呼叫另一個 workflow，巢狀一層。

超越扇出：品質模式

扇出只是基本盤。編排真正有趣的部分，是用結構讓答案更可能為真：

  • 對抗式驗證（adversarial verify）——針對每個發現，生成獨立的懷疑者 agent，明確要求它們反駁該發現；如果多數反駁成功，這個發現就淘汰。這能在看似合理但其實錯誤的結果到你面前之前把它們濾掉。
  • 評審團（judge panel）——從不同角度對同一問題做出多個獨立嘗試，由平行的評審打分，最終答案由勝出者加上其餘方案的最佳想法綜整而成。
  • 循環到枯竭（loop-until-dry）——面對規模未知的「找出所有 X」任務，持續生成搜尋者，直到連續好幾輪都找不到新東西為止。

這些模式值得專門一堂課——Session 28：編排品質模式逐一附程式碼講解。目前先記住這個重點：答案品質變成了你如何編排的結構性屬性，而不只是模型本身的屬性。

單打獨鬥、子代理，還是 Workflow？

機制越多不見得越好。這是一張誠實的決策表：

情境選擇原因
查單一事實，而且你知道在哪個檔案單打獨鬥（不委派）委派的開銷不划算——直接讀就好
多檔案閱讀、搜尋、探索子代理（Agent tool）主上下文只留結論，不留整批檔案內容
需要記得先前工作的合作者具名 agent + SendMessage帶著完整上下文繼續，而不是重新開始
跨多項目的多階段流程，需要驗證或續跑Workflow可重複的控制流程、平行化、進度檢視、同 session 續跑

如何啟用

Workflow 是**選擇性啟用（opt-in）**的——單一 workflow 可能生成數十個 agent、消耗可觀的 token 量，所以 harness 要求你明確要求這種規模。不啟用時，Claude Code 會使用個別子代理或獨自工作。三種啟用方式：

  1. 直接說：在 prompt 中寫上「use a workflow」做一次性啟用。
  2. Ultracode：在 prompt 中加入關鍵字「ultracode」，或透過 /effort 為整個 session 啟用。Ultracode = xhigh 推理強度 + 在每個實質任務上常駐的多代理 workflow 編排。（完整指南：Ultracode 與 Effort 等級。）
  3. 透過 skill：skill 的指示可以指引 Claude Code 為其任務使用 workflow 進行編排。

大型執行前先用小範圍試跑、檢查預估規模，並在 /workflows 監看 token 用量。Size guideline 能影響腳本規模，但不是花費上限。

重點結論

Workflow 是樂譜，不是獨奏者。Claude Code 撰寫 JavaScript 來決定什麼執行、何時執行、以什麼順序執行——並把判斷交給子代理。你得到的是可檢視、可重新執行的控制流程、平行化與進度可見性；同時保留一個重要事實：模型輸出仍會變動，也仍需驗證。

下次某個任務對單一上下文視窗來說太大時，別要求一個更大的 agent。請要求一個交響樂團。