ultracode 上限工具包：五個設定、扇出檢查表與實測對照

重點摘要與結論

Ultracode 不會讓 Claude Code 變聰明。它改變的是模型被告知的內容，並移除三道防護，所以一次執行花得更多，也停得更晚。
規則：只有在測試套件或規則集能評判輸出，而且工作能拆成彼此獨立的片段時，才展開成多個 agent。其他一律用 high 一般執行。
五個設定能替一次執行設上限：把工作流程規模準則設成 small、併行 agent 上限設為 4、讓每個工作流程 agent 都用同一個較便宜的模型、用關鍵字而不用開關，以及關閉用量上限時的自動繼續。
承載這些上限的兩個檔案是 settings.json 和 ultracode-caps.sh。檢查表是 when-to-fan-out.md。實測的對照資料在 paired-runs.csv。
規模準則是建議，不是上限。在我們自己的執行中，它寫的是少於 5 個 agent，而那次執行用了 9 個。

來源怎麼說

關鍵字與開關。 在 prompt 中輸入 ultracode，會讓那一個任務選擇以工作流程執行。用你自己的話提出，例如「use a workflow」，效果等同於同一種選擇加入 s1。在以 -p 傳入的 prompt、未經標記的 Agent SDK 輸入，或排程任務中，關鍵字不會有作用 s1。開關則不同。開啟 ultracode 後，Claude 會為每個實質任務規劃一個工作流程，一個請求可能連續變成好幾個工作流程 s1。文件還補充，開啟 ultracode 的 session 會比關閉時做同樣的工作更快碰到 session 或每週上限 s1。

被注入的那句話。 開啟 ultracode 後，workflow-authoring 參考文件寫道：「author and run a workflow for every substantive task by default. The goal is the most exhaustive, correct answer you can produce」，並寫道「token cost is not a constraint.」同樣的文字也被一則標題為「Ultracode overrides the workflow size guideline」的公開 issue 引用 s8。連續的每個工作流程都有自己的 agent 預算，所以四個各 15 個 agent 的階段共計 60 個 agent，而沒有任何單一工作流程違反準則 s8。

三道防護。 Ultracode 關掉三項檢查。Large workflow 警告不會出現。Session 的併行 subagent 限制，對 Claude 用 Agent 工具產生的 subagent 不會強制執行。在 auto 權限模式下，第一次啟動工作流程時不會請你核准 s1。

規模準則。 Small 表示少於 5 個 agent，medium 少於 10 個，large 少於 50 個。預設是 medium，若是 Pro 方案且版本為 v2.1.271 或更新，則預設為 small。Claude Code 把它當成建議而不是上限傳給模型，所以要求其他規模的 prompt 仍然可以覆蓋它 s1。硬性限制是預設 16 個併行 agent，以及每次執行 1,000 個 agent。大型工作流程警告在超過 25 個 agent 或預估 150 萬個 token 時觸發，而且只是警告 s1。

我們自己的執行。 我們在一個只有兩個檔案、16 行程式碼的沙盒上輸入關鍵字，規模準則設為 small，並要求唯讀審查。這次執行用了 9 個 agent：2 個 finder 和 7 個 verifier。每個 finder 讀了大約 45.2k 個 token。我們沒有對同一個 prompt 做一般執行，所以沒有自己的成對數據。

成對測試。 在 200 美元的方案上，一位開發者把同一份規格交給一次一般執行和一次 ultracode 執行。兩者都通過 136/136 項隱藏檢查。一般執行在 25 分鐘內完成，用掉 5 小時上限的 8%。Ultracode 執行在 76 分鐘時被切斷，已用掉 18%，它在兩個團隊（9 個和 3 個）中使用了 12 個 agent，而不是 1,000 個。以每分鐘計算，消耗速度大致相同：只是它不會停 s3。

Pro 方案上的另外三組對照。 單一 agent 對工作流程，發現相同：115k 對 972k 個 token、52k 對 936k、102k 對 683k。/usage 用量計分別移動了 4 對 12、7 對 12 和 4 對 8 點，作者將其總結為大約兩倍的額度，最高到三倍。Opus 方案腳本的牆上時間是 173 秒對 178 秒。在四個獨立的研究工作上，平行快了 1.6 倍，但 token 是 2.3 倍 s4。

30 倍那一組。 一個以 xhigh 執行的單一 agent，花了 1 小時 13 分鐘，以 API 價格計約 18 美元。Max 加上 ultracode 花了 9 小時 14 分鐘，有 40 個 subagent，約 554 美元。各只跑一次，採 API 牌價，不是訂閱帳單 s11。

一組對照長什麼樣。 一個公開的測試 repo 裡有一組同一任務的單一 agent 對工作流程對照。單一 agent 用了 181,646 個 token，工作流程用了 1,326,703 個。以 API 價格計，成本是 $0.2678 對 $1.3744。牆上時間是 43 秒對 80 秒，session 用量計移動了 +0 對 +12 點 s22。這只是一組對照，所以把它當成一種形狀來讀，而不是定律。文件把 subagent 和工作流程列為 token 的驅動因素：工作流程產生的每個 agent，都會在主對話之上送出自己的請求 s5。Anthropic 的研究團隊量到，agent 的 token 約是聊天的 4 倍，多 agent 系統約是 15 倍 s20。

划算的地方：Bun。 Bun 用大約 50 個動態工作流程連續跑了 11 天，從 Zig 改寫成 Rust。原始碼是 535,496 行 Zig，從開始到所有平台上 100% 的測試套件通過，花了 11 天 s19。裁判是一個既有的測試套件。

划算的地方：bug 搜尋。 Anthropic 在一個 116k 行的程式碼庫中植入了 70 個 bug。在 3 次執行中，單一 agent 找到 14、15 和 27 個。工作流程在它的 3 次執行中每次都找到 66 個 s24。那個測試是在 Managed Agents 上跑的，也就是 API 產品，不是 Claude Code。Anthropic 沒有給出成本，並建議從範圍明確的任務開始 s24。發表部落格說，大多數傳統的程式開發任務並不需要 5 人審查小組 s2。

失控的執行。 在 Max 20x 方案上，一支由模型寫成的腳本在 51 分鐘內啟動了 221 個 agent。第一次出現 session 上限錯誤之後，又啟動了 189 個 agent。回報者的表格計算出含快取共 47,465,299 個 token s7。回報者提出兩點但書：後來的 189 個 agent 沒有記錄到模型回應，以及腳本的 fallback 在合併沒有回傳任何東西時仍繼續派送。那次執行是在 v2.1.266，早於「在用量上限暫停」的功能 s7。第二份公開回報描述了兩個工作流程，分別有 56 和 104 個 agent，用掉 1,472,855 和 1,752,360 個 token，160 個 agent 中有 92 個因 session 上限而失敗 s21。回報者說，使用者並未啟用 ultracode，卻被回報為開啟。

這些槓桿。 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS 的值為 1 到 256，需要 v2.1.269 s10。CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 讓每個工作流程 agent 都用同一個模型，其他 subagent 維持原本的，從 v2.1.296 開始 s18。開啟 autoContinueAtUsageLimit 後，碰到上限的執行會暫停並在重置時繼續，最多等待兩次，第三次時 agent 就會失敗。關閉時，受影響的 agent 在牆邊失敗 s1。發表部落格說，寫在 prompt 裡的預算，例如「use 10k tokens」，就會設下上限 s2。/workflows 檢視會顯示每個 agent 的 token 用量，x 會停止這次執行 s1。/usage 會標出占近期用量 10% 或以上的行為，而 v2.1.299 新增了針對工作流程的警告 s5 s18。

上限工具包

設定區塊。上限 1 是規模準則，上限 4 是讓 ultracode 保持 false，使關鍵字成為唯一的入口，上限 5 是自動繼續關閉。把它放進 .claude/settings.json 或任何設定檔。workflowSizeGuideline 這個鍵從 v2.1.219 起在任何設定檔中都能使用 s1。

settings.json

{
  "workflowSizeGuideline": "small",
  "ultracode": false,
  "autoContinueAtUsageLimit": false
}

settings.json on GitHub

環境變數那幾行。上限 2 和 3。請把占位符換成你要讓工作流程 agent 使用的模型的完整 id。

ultracode-caps.sh

#!/usr/bin/env bash
# Source this file before you launch Claude Code: `source ultracode-caps.sh && claude`.
# These two lines are caps 2 and 3 of the five. Caps 1, 4 and 5 live in settings.json.

# Cap 2: at most 4 workflow agents run at once. The default is 16 (fewer on a machine
# with few CPUs). Accepted values are 1 to 256. Needs Claude Code v2.1.269 or later.
export CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=4

# Cap 3: run every workflow agent on one cheaper model, while your other subagents
# keep theirs. Replace the placeholder with the full model id you want to pay for.
# Needs Claude Code v2.1.296 or later.
export CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL="<your-cheaper-model-id>"

# Optional kill switch for a shared machine: no workflows at all.
# export CLAUDE_CODE_DISABLE_WORKFLOWS=1

ultracode-caps.sh on GitHub

在輸入關鍵字之前要跑一遍的檢查表。

when-to-fan-out.md

# When to fan out: the two-condition checklist

Fan out (use the ultracode keyword in one prompt) only if both answers are yes.

1. Does a test suite or a rule set judge the output?
   - [ ] A suite that already exists and says pass or fail without anyone's opinion.
   - [ ] Or a written rule file the output is reviewed against.
2. Does the job split into independent pieces?
   - [ ] No piece waits on the result of another piece.
   - [ ] Each piece can be checked on its own.

If either answer is no, run plain at high effort. A plain run costs one bill. A
workflow costs one bill per agent.

Jobs that usually pass both tests:
- A port or migration across many files with a test suite as the judge.
- A review of a whole codebase against a rule file.
- A translation of many files with the same prompt.
- A cleanup pass over a pile of similar documents.

Jobs that usually fail one of them:
- A small feature, a bug fix, a refactor of one module.
- Anything where "good" is a matter of taste.
- A chain of steps where each one needs the previous result.

Before you start:
- [ ] Run a slice first (one folder, ten files) and read the token total.
- [ ] Put a budget in the prompt, for example "use 10k tokens".
- [ ] Open /workflows and watch per-agent tokens. Press x to stop.
- [ ] After the run, open /usage and read the share that went to workflows.

when-to-fan-out.md on GitHub

來源中實測的對照與案例，每筆一列，附上來源 id。

paired-runs.csv

source_id,run,measure,baseline,workflow_or_fanout,note
s22,rebuild-your-claude-md pair (rep 2),tokens,181646,1326703,"all four usage fields summed, 14 agent transcripts on the workflow side"
s22,rebuild-your-claude-md pair (rep 2),API cost in USD,0.2678,1.3744,single agent vs workflow
s22,rebuild-your-claude-md pair (rep 2),wall time in seconds,43,80,single agent vs workflow
s22,rebuild-your-claude-md pair (rep 2),session meter points,+0,+12,"/usage before to after: 17% to 17% vs 19% to 31%"
s24,70 planted bugs in 116k lines,bugs found,"14, 15 and 27 (3 runs)","66 in each of 3 runs","Managed Agents, not Claude Code; no cost given"
s19,Bun port from Zig to Rust,test suite passing,,100%,"about 50 dynamic workflows, 11 days, 535,496 lines of Zig"
s6,fixed worker and gate files,tokens for workflow execution and monitoring,100%,about 20%,"self-reported, no plan stated; runs 5 to 6 hours down to 20 to 40 minutes"
s7,runaway run on Max 20x,agents started,,221,"51 minutes; 189 started after the first session-limit error; 47,465,299 tokens including cache"
s21,ultracode reported on without the user enabling it,agents started,,"56 and 104","1,472,855 and 1,752,360 tokens; 92 of 160 agents failed with the session limit"
s20,multi-agent research system,tokens vs a chat,about 4x for an agent,about 15x for multi-agent,Anthropic's own data
s3,same spec on a $200 plan,hidden checks passed,136/136,136/136,"both runs perfect"
s3,same spec on a $200 plan,time and 5-hour limit used,"25 min, 8%","76 min (cut off), 18%","12 agents in two teams (9 and 3)"
s4,Opus plan script,tokens,115k,972k,"Pro plan; /usage 4 vs 12 points; 173 s vs 178 s"
s4,compact script,tokens,52k,936k,"Pro plan; /usage 7 vs 12 points"
s4,Claude.md script,tokens,102k,683k,"Pro plan; /usage 4 vs 8 points"
s4,four independent research jobs,time and tokens,"102 s, about 33k","about 64 s, 76k","parallel 1.6x faster for 2.3x tokens"
s11,Cybercity,time and API cost,"1 h 13 m, about $18 (1 agent)","9 h 14 m, about $554 (40 subagents)","xhigh vs max with ultracode; one run each; API list prices"

paired-runs.csv on GitHub

關於這個工具包的兩點說明。ultracode 這個鍵，只有在你否則會開著開關啟動 session 時才有意義，把它保持 false，表示每一次展開成多個 agent，都是你在一個 prompt 裡做的決定。完全關閉工作流程會同時移除關鍵字與開關：在 ~/.claude/settings.json 設定 "disableWorkflows": true s1。

週一就做這些

把 settings.json 複製到你的專案設定中，並確認 /config 顯示規模準則為 small。
在你啟動 Claude Code 的 shell 中 source ultracode-caps.sh，並用真實的模型 id 取代占位符。
確認 /effort 裡的 ultracode 開關是關閉的，想展開成多個 agent 時，就在單一 prompt 中使用關鍵字。
在任何展開之前，回答 when-to-fan-out.md 裡的兩個問題。只要有一個答案是否定的，就用 high 一般執行。
先跑一小段，在擴大工作之前先看 /workflows 裡的 token 總數。
在 prompt 裡加上預算，例如「use 10k tokens」。
第一次執行時讓 /workflows 保持開啟，如果 agent 數量爬升超過你的預期，就按 x。
執行之後，打開 /usage，記下花在工作流程上的占比。

延伸閱讀

自己固定 worker 與 gate，而不是讓模型去寫。 一篇 Hacker News 貼文回報，把工作流程執行與監控的 token 花費降到原本的大約 20%，原本要 5 到 6 小時的工作流程現在只要 20 到 40 分鐘。這是自行回報的，也沒有說明方案 s6。方法有兩個部分。一個 workflow-worker agent 檔案拿到計畫中的一個片段，並有嚴格的權限，只能替自己負責的部分寫測試與執行測試。一個 workflow-gate agent 檔案接收平行 agent 的結果，而序列檢查則移到一個有兩個目標的 Makefile：make workflow-serial-gate 檢查 git 樹並對有變動的部分跑測試，make workflow-final-gate 則對全部內容跑乾淨的測試 s6。同一篇貼文說，複雜計畫過去要花 10 分鐘的 gate 檢查，現在只要一秒鐘。那 20% 涵蓋的是執行與監控，不包括計畫的建立與實作。想試的話，把這兩個 agent 檔案寫一次、放在 repo 裡，然後讓你的工作流程 prompt 指向它們。

在信任生成的腳本之前，先讀失控回報。 那則 issue 顯示了各階段的表格，以及 189 個多餘 agent 背後的那個模式：當合併 agent 沒有回傳任何東西時，腳本就退回原始清單並繼續 s7。請向模型要求在 agent 失敗時就停止的腳本。對任何你不盯著看的執行，都讓自動繼續保持關閉。

了解準則為什麼會輸。 Issue 92631 把準則的文字和 ultracode 的那句話並列，說明兩者衝突時為什麼後者會贏 s8。如果你想要硬性上限，併行數變數限制同時能跑多少 agent，而 prompt 裡的預算則限制它們能花多少。

寬範圍的工作，參考發表串文。 最尖銳的首日反彈就在發表串文裡，留言像是「an exciting new way to burn up as many tokens as possible」和「Quantity of output is not the issue right now. Quality is.」s9。人們在那裡回報的成果都有相同的形狀：依規則檔案做審查、翻譯程式碼庫、整理掃描頁面。

Managed Agents 是不同的產品。 那個 70 個 bug 的測試用的是 Managed Agents 的動態工作流程，只提供 API。如果你在 API 上開發，就照 Anthropic 的建議，從範圍明確的任務開始 s24。Claude Code 的設定不會沿用過去。

什麼不要相信。 沒有方案、沒有數字的額度軼事都是二手的。有位留言者說 6 個 agent 吃掉了 4 小時的額度，另一位說，他透過自己的 clone，在另一家廠商的便宜模型上，把將近 20 億個 token 的移植花了 20 美元 s23 s9。這兩者都不是在方案上對 Claude Code 的量測。只有附上方案、模型、版本和任務的數字，才值得記進你的筆記。

常見問題

關鍵字的花費和開關一樣嗎？ 不一樣。關鍵字把一個任務當成工作流程執行。開關則為每個實質任務規劃一個工作流程，所以一個請求可能變成好幾個 s1。兩者都是疊加在你的對話之上花錢，因為每個 agent 都會送出自己的請求 s5。

把規模準則設成 small，就會把一次執行限制在 4 個 agent 嗎？ 不會。它是傳給模型的建議，prompt 或 ultracode 的那句話都可以覆蓋它 s1 s8。在我們的執行中，它寫的是少於 5 個，而那次執行用了 9 個。硬性限制是併行數變數，以及你自己的手動停止。

當一次執行碰到我的用量上限時會怎樣？ 開啟 autoContinueAtUsageLimit 後，互動式 claude.ai session 會暫停這次執行並在重置時繼續，最多等待兩次，從 v2.1.271 起適用。更早的版本會讓受影響的 agent 失敗 s1。關閉時，agent 在上限處失敗，這次執行就此結束。

為什麼工作流程 agent 要用較便宜的模型？ 工作流程的大部分是檢查，而且每個 agent 都會送出自己的請求。CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 把所有工作流程 agent 放在同一個模型上，並且不動你其他的 subagent s18。在你仰賴它之前，先用一小段檢查結果。

我還能用 ultracode 嗎？ 可以，對於能通過檢查表裡兩個問題的工作。Bun 的移植有完整的測試套件當裁判 s19。對於小功能或修 bug，用 high 一般執行是預設做法。