Effort 等級與 Ultracode

你將學到什麼

第 25 堂課談的是要用哪個模型。這堂課談第二個旋鈕：那個模型要想多深。在 Fable 5 世代，Claude Code 把 reasoning effort（推理強度）開放為第一級、由使用者控制的設定 — 從快速的低強度掃過，一路到 ultracode：一種明確告訴 harness「token 成本不是限制」的模式。

完成後，你將了解：

• /effort 控制什麼，以及每個等級各犧牲了什麼
• ultracode 究竟是什麼（xhigh effort + 動態 workflow 編排）
• 兩種啟用方式 — 在提示中加關鍵字，或 session 層級的切換
• 為什麼 ultracode 是「主動選擇加入」而不是自動啟用
• 像 +500k 這樣的 token 預算指令，以及 budget 物件的硬上限語義
• 如何在 workflow 腳本中為每個子代理（subagent）各自設定 effort

問題所在

一個模型配一種固定的思考深度，無法應付真實工作。重新命名一個變數和稽核付款模組不是同一種任務，但多年來你手上唯一的品質旋鈕就是模型選擇。這留下兩種反覆出現的失敗模式：

1. 在瑣碎工作上多付錢。 對一行修改動用深度推理純屬浪費 — 回應更慢、token 更多、結果相同。
2. 在真正重要的任務上想得不夠。 那一次需要窮盡式、對抗性審視的遷移審查，得到的努力程度跟其他所有事一樣，而你事後才發現。

也沒有誠實表達規模的方式。如果你想讓 Claude Code 對一個問題投入數十個 agent，你只能寄望「be very thorough」這類提示措辭真的轉化為實際行為 — 而且你沒有任何機制可以說「最多花到這裡，不能再多」。成本控制是願望，不是強制。（第 21 堂課的成本技巧 — 見 /zh-tw/tutorials/s21-cost-optimization — 是在繞過這個缺口；這個世代則把它補上了。）

如何運作

/effort 旋鈕

/effort 設定該 session 的推理強度。共有四個等級，外加一個特殊的頂級設定：

/effort
   │
   ├─ low      less reasoning — fast, cheap; mechanical stages
   ├─ medium   the middle of the dial
   ├─ high     hard debugging, verification, judgment calls
   ├─ xhigh    most exhaustive reasoning on demand
   │
   └─ ultracode = xhigh + dynamic workflow orchestration

這筆交易正如你所料：effort 越低，回應越快越便宜；effort 越高，推理越徹底，token 成本也越高。整個世代浮現出的指引很一致 — 便宜、機械性的工作用低 effort；驗證與判斷用高階層級。

和 /model 一樣，你的 /effort 選擇可以持久保存：兩個指令都能把選擇存成新 session 的預設值。

Ultracode：xhigh 加上編排

Ultracode 不只是另一個 effort 等級。 它是 xhigh effort 加上動態 workflow 編排（orchestration）。開啟 ultracode 後，Claude Code 被指示要：

• 以最窮盡、最正確的答案為優化目標 — 而不是最快或最便宜的
• 在每一個實質任務上使用多代理 Workflow 編排
• 把 token 成本明確視為不是限制

最後一點是它的定義性特徵。正常運作時，harness 會在品質與成本之間權衡。在 ultracode 之下，這個權衡被刻意移除：指令是「不計代價，把答案做對」。

兩種啟用方式

1. 關鍵字。 在提示中任何位置加上 “ultracode” 這個詞，那一輪就會以 ultracode 模式執行。這是一次性的選擇加入 — 下一個提示就回到正常模式。

> Audit src/payments/ for correctness bugs. ultracode

2. session 切換。 在 session 層級選擇 ultracode（例如透過 /effort）。這是常駐的選擇加入：session 中的每個實質任務都會得到完整待遇，直到你關掉為止。

為什麼是選擇加入

Ultracode 的 workflow 可能生成數十個 agent、消耗大量 token。這種規模正是重點所在 — 但也正因如此，harness 拒絕悄悄啟用它。設計原則是：這種規模必須由使用者明確要求。 沒有提示語意的模糊空間，也不會有模型自作主張把你的 token 支出翻上好幾倍。你說 ultracode，你才得到 ultracode。

Token 預算指令

反方向的控制也存在：與其移除成本限制，你可以把它變成一個硬性數字。在提示中寫下像 +500k 這樣的指令，那一輪就有了 token 目標。

在 Workflow 腳本中，這個目標以 budget 物件的形式呈現：

成員	意義
budget.total	目標值（一個數字），若未給指令則為 null
budget.spent()	目前已消耗的 token 數
budget.remaining()	距離上限還剩的 token 數

兩個性質很重要：

• 資源池是共享的。 一份預算涵蓋主迴圈以及該輪的所有 workflow。沒有可以鑽漏洞的 per-workflow 子額度。
• 目標是硬上限。 一旦 spent() 達到 total，後續的 agent() 呼叫會直接拋出例外。這不是模型盡力遵守的軟性提示 — 而是 harness 層的強制執行。寫得好的腳本會在生成 agent 前檢查 remaining() 並優雅降級；粗心的腳本會死在半路上。

Workflow 中的 per-agent effort

Effort 不只是 session 層級的旋鈕。Workflow 腳本可以為每個子代理各自設定推理強度：

agent(prompt, { effort: 'low' })    // low | medium | high | xhigh | max

注意，per-subagent 的刻度比 session 旋鈕多走一步：它包含 max 層級。這是 effort 從偏好設定變成架構工具的地方。模式如下：

• 便宜的機械性階段（讀檔、搜尋、格式化、扇出探索）→ low
• 困難的驗證／評判／彙整階段 → 高階層級

同樣的原則也適用於模型選擇（第 25 堂課的三個覆寫點），而且兩個旋鈕可以組合：一個 haiku 級的搜尋者跑 low effort、一個頂級評審跑 high effort，可以同時住在同一份腳本裡，相隔三行。

實作範例

這是組合技的實際樣貌：一輪同時選擇加入 ultracode 並附上硬預算 —

> Audit src/payments/ for correctness bugs. ultracode +500k

— 以及一個預算防護的探索迴圈（budget-guarded discovery loop），這是「持續找下去，直到再也找不到新發現或錢快花完」的經典腳本形狀。每一輪由便宜的搜尋者以 low effort 扇出；同時保留一筆預備金，確保最後一定跑得動一個 high effort 的彙整 agent。

export const meta = {
  name: 'budget-guarded-audit',
  description: 'Find issues until discovery runs dry or the token budget runs low',
  phases: [{ title: 'Discover' }, { title: 'Synthesize' }],
};

phase('Discover');

const seen = [];   // dedup against everything seen so far
let dryRounds = 0;
let round = 0;

while (dryRounds < 2) {
  round += 1;

  // budget.total is null when the user gave no "+500k"-style directive.
  // Guard BEFORE spawning: once spent() reaches total, agent() throws.
  if (budget.total !== null && budget.remaining() < 60000) {
    log(`Budget guard: ${budget.spent()} spent, ` +
        `${budget.remaining()} left — reserving the rest for synthesis.`);
    break;
  }

  const results = await parallel([
    () => agent(
      `Round ${round}: hunt for correctness bugs in src/payments/. ` +
      `Known findings (do not repeat): ${seen.join('; ') || 'none yet'}. ` +
      `Return one line per NEW finding, or "NONE".`,
      { label: `finder-${round}-bugs`, phase: 'Discover', effort: 'low' }
    ),
    () => agent(
      `Round ${round}: hunt for error-handling gaps in src/payments/. ` +
      `Known findings (do not repeat): ${seen.join('; ') || 'none yet'}. ` +
      `Return one line per NEW finding, or "NONE".`,
      { label: `finder-${round}-errors`, phase: 'Discover', effort: 'low' }
    ),
  ]);

  // parallel() never rejects; a thunk that throws resolves to null.
  const fresh = results
    .filter(Boolean)
    .flatMap((text) => text.split('\n'))
    .filter((line) => line.trim() && line.trim() !== 'NONE');

  if (fresh.length === 0) {
    dryRounds += 1;
  } else {
    dryRounds = 0;
    seen.push(...fresh);
  }

  log(`Round ${round}: ${fresh.length} new, ${budget.spent()} tokens spent.`);
}

phase('Synthesize');

const report = await agent(
  'Verify and write up these audit findings, most severe first:\n' +
  seen.map((f, i) => `${i + 1}. ${f}`).join('\n'),
  { label: 'synthesis', phase: 'Synthesize', effort: 'high' }
);

log(report ? 'Audit complete.' : 'Synthesis agent was skipped.');

逐一看承重的幾行：

• 防護檢查在每一輪之前執行，而不是之後。 因為上限是靠 agent() 拋出例外來強制執行的，在生成之後才檢查 remaining() 已經太遲。60k 的預備金是腳本自己的策略 — 為彙整階段留足空間。
• null 檢查很重要。 提示中沒有 +500k 指令時，budget.total 是 null，迴圈就只受「連續空手回合」限制。
• Effort 按角色拆分。 搜尋者用 low — 它們負責廣度，不負責判斷。彙整用 high — 那是唯一一個判斷錯誤會毀掉輸出的地方。
• 去重是對照所有 seen 過的發現。 每一輪的提示都帶著先前的發現，搜尋者才不會永遠重複翻出同樣的東西。
• .filter(Boolean) 同時處理兩種失敗形態：parallel() 會把拋出例外的 thunk 轉成 null；而使用者跳過某個 agent、或 agent 死於終端性 API 錯誤時，agent() 本身也會回傳 null。

這份腳本背後完整的 Workflow API — meta、phase()、pipeline() 與 parallel() 的差異、resume 語義 — 是第 27 堂課的主題。

前後對比

之前	Fable 5 世代
品質旋鈕 = 只有模型選擇	兩個獨立旋鈕：模型 × effort
用「請認真想」在提示裡求情	/effort 等級：low / medium / high / xhigh
大規模的徹底程度：無法預測	Ultracode：xhigh + workflow 編排，白紙黑字保證
大筆支出可能悄悄發生	規模需要明確選擇加入（關鍵字或切換）
成本控制：盯著錶祈禱	+500k → 硬上限；agent() 在額度用盡時拋出例外
整個 session 一種 effort	Workflow 腳本中的 per-subagent effort（最高到 max）

關鍵洞見

品質對成本的取捨，成了使用者手中的旋鈕，而不是模型的常數。

這堂課的每個部分都是同一個想法的不同角度。/effort 把「用哪個模型」和「它多用力」分開。Ultracode 是把旋鈕釘死在最大值 — 且 harness 以契約層級忽略成本。+500k 指令是把旋鈕指向一個數字 — 且 harness 以契約層級拒絕超過它。而 per-agent 的 effort 把旋鈕下放到 workflow 的個別階段。

注意這些保證住在哪裡。Ultracode 的窮盡性和預算的上限，都是由 harness 強制執行的 — 一個在額度用盡時拋出例外的 agent() 呼叫是結構性的，就像 hook 擋下工具呼叫；而不是行為性的，像一條模型努力記住的指令。這正是這個世代的招牌動作：關於 effort 與成本的承諾，從提示裡搬進了機器裡。

刻意地使用這顆旋鈕：機械性的九成工作用低 effort，判斷錯誤代價高的地方用高階層級，正確性真正壓過成本時用 ultracode — 想把這筆交易白紙黑字設個上限時，就加一條預算指令。

下一堂課

第 27 堂課將打開這堂課一直隱約指向的機械裝置：Workflow 工具 — Claude Code 的腳本化多代理編排，控制流程住在確定性的 JavaScript 裡，判斷住在模型裡。見 /zh-tw/tutorials/s27-workflow-orchestration。