AIDive

動画パック

ultracode上限キット: 5つの設定、ファンアウトのチェックリスト、測定したペア

11 分で読めます

TL;DRと結論

  • ultracodeはClaude Codeを賢くしません。モデルに伝える内容を変え、3つのガードを外すので、実行はより多く使い、より遅く止まります。
  • ルール: テストスイートまたはルールセットが出力を判定し、仕事が独立した部分に分かれるときだけファンアウトする。それ以外はhighで普通に走らせる。
  • 実行に上限をかける設定は5つ: workflowサイズの目安をsmallにする、同時エージェント数の上限を4にする、すべてのworkflowエージェントを1つの安いモデルで動かす、トグルではなくキーワードを使う、usage limitでの自動継続をオフにする。
  • 上限を担うファイルは settings.json と ultracode-caps.sh の2つです。チェックリストは when-to-fan-out.md、測定したペアは paired-runs.csv にあります。
  • サイズの目安は助言であり、上限ではありません。私たち自身の実行では「5未満」と示されていたのに、実行は9を使いました。

ソースが語ること

キーワードとトグル。 プロンプトに ultracode と入力すると、そのタスクだけがworkflowに切り替わります。「use a workflow」のように自分の言葉で頼んでも、同じオプトインとして働きます s1。キーワードは、-p で渡したプロンプト、スタンプのないAgent SDKの入力、スケジュールされたタスクでは何もしません s1。トグルは違います。ultracodeがオンだと、Claudeはすべての実質的なタスクでworkflowを計画し、1つの依頼が続けて複数のworkflowになることがあります s1。ドキュメントには、ultracodeがオンのセッションは、オフで同じ作業をするより早くセッション上限や週間上限に達する、とも書かれています s1。

注入される一文。 ultracodeがオンのとき、workflow作成用のリファレンスはこう述べます。「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。連続するworkflowはそれぞれ自分のエージェント予算を持つので、15エージェントの4フェーズは60エージェントになり、それでも単独のworkflowは目安を破りません s8。

3つのガード。 ultracodeは3つのチェックをオフにします。Large workflow の警告が出ません。セッションの同時サブエージェント制限は、ClaudeがAgentツールで生み出すサブエージェントには適用されません。autoのパーミッションモードでは、最初のworkflow起動の承認を求められません s1。

サイズの目安。 smallは5エージェント未満、mediumは10未満、largeは50未満です。デフォルトはmediumで、v2.1.271以降のProプランではsmallです。Claude Codeはこれを上限ではなく助言としてモデルに送るので、別の規模を求めるプロンプトがそれを上書きします s1。ハードな制限は、デフォルトで同時16エージェント、1回の実行で1,000エージェントです。大規模workflowの警告は、25エージェントまたは予測150万トークンを超えると出ますが、出るのは警告だけです s1。

私たち自身の実行。 2ファイル、16行のコードのサンドボックスで、サイズの目安をsmallにしてキーワードを入力し、読み取り専用のレビューを頼みました。実行は9エージェント(finder 2、verifier 7)を使い、各finderは約45.2kトークンを読みました。同じプロンプトの通常実行は行っていないので、自前のペアの数字はありません。

ペアテスト。 200ドルのプランで、ある開発者が通常実行とultracode実行に同じ仕様を渡しました。どちらも隠しチェック136/136に通りました。通常実行は25分で終わり、5時間上限の8%でした。ultracode実行は76分で打ち切られ、18%が消えており、使ったのは2つのチーム(9と3)に分かれた12エージェントで、1,000ではありません。1分あたりの燃え方はほぼ同じで、ただ止まらなかったのです s3。

Proプランでのさらに3組のペア。 単独エージェント対workflow、発見は同じ: 115k対972k、52k対936k、102k対683kトークン。/usageメーターは4対12、7対12、4対8ポイント動き、著者はこれを枠のおよそ2倍、最大3倍とまとめています。Opusのプランスクリプトでの実時間は173秒対178秒でした。独立した4つの調査ジョブでは、並列は1.6倍速く、トークンは2.3倍でした s4。

30倍のペア。 xhighの単独エージェントは1時間13分、APIの価格で約18ドル。ultracode付きのmaxは9時間14分、40のサブエージェントで約554ドルでした。それぞれ1回の実行で、APIの定価であり、サブスクリプションでの請求ではありません s11。

ペアの実例。 公開のテストリポジトリに、同じタスクでの単独エージェント対workflowのペアが1つあります。単独エージェントは181,646トークン、workflowは1,326,703トークンでした。APIの価格でのコストは0.2678ドル対1.3744ドル、実時間は43秒対80秒、セッションメーターの動きは+0対+12ポイントでした s22。これは1つのペアなので、法則ではなく形として読んでください。ドキュメントはサブエージェントとworkflowをトークンを押し上げる要因に挙げています。workflowが生み出す各エージェントが、メインの会話の上に自分のリクエストを送るからです s5。Anthropicのリサーチチームは、チャットに比べてエージェントで約4倍、マルチエージェントシステムで約15倍のトークンを測定しています s20。

元が取れる場面: Bun。 Bunは、約50の動的workflowを11日間連続で走らせ、ZigからRustに書き直されました。ソースは535,496行のZigで、移植は着手から、全プラットフォームでテストスイートの100%が通るところまで11日で到達しました s19。判定役は既存のテストスイートでした。

元が取れる場面: バグ探し。 Anthropicは116k行のコードベースに70個のバグを仕込みました。3回の実行で、単独エージェントが見つけたのは14、15、27。workflowは3回の実行のそれぞれで66を見つけました s24。このテストはClaude Codeではなく、APIの製品であるManaged Agentsで行われました。Anthropicはそのコストを示しておらず、範囲を絞ったタスクから始めるよう勧めています s24。ローンチのブログは、従来のコーディングタスクの大半には5人のレビュアーのパネルは要らない、と述べています s2。

暴走した実行。 Max 20xプランで、モデルが書いたスクリプトが51分で221のエージェントを起動しました。最初のセッション上限エラーのあとに、さらに189のエージェントが起動しました。報告者の表は、キャッシュ込みで47,465,299トークンを数えています s7。報告者による2つの注記があります。後から起動した189のエージェントにはモデルの応答の記録がなく、mergeが何も返さなかったときにスクリプトのフォールバックが配布を続けた、というものです。その実行はv2.1.266で、usage limitでの一時停止より前のものでした s7。2つ目の公開報告は、56と104エージェントの2つのworkflow、1,472,855と1,752,360トークンで、160エージェント中92がセッション上限で失敗した事例です s21。報告者によれば、ultracodeはユーザーが有効にしていないのにオンと報告されていました。

レバー。 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS は1から256の値を取り、v2.1.269が必要です s10。CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL は、他のサブエージェントのモデルはそのままで、すべてのworkflowエージェントを1つのモデルで動かします。v2.1.296からです s18。autoContinueAtUsageLimit がオンだと、上限に当たった実行は一時停止してリセットで再開し、待機は最大2回で、3回目にはエージェントが失敗します。オフだと、影響を受けたエージェントは壁で失敗します s1。ローンチのブログによると、「use 10k tokens」のようにプロンプトに書いた予算が上限になります s2。/workflows ビューには各エージェントのトークン使用量が表示され、x で実行が止まります s1。/usage は最近の使用量の10%以上を占める挙動にフラグを立て、v2.1.299でworkflowの警告が追加されました s5 s18。

上限キット

settingsのブロックです。上限1はサイズの目安、上限4はキーワードだけが入口になるよう ultracode をfalseのままにすること、上限5はauto-continueのオフです。.claude/settings.json か任意のsettingsファイルに置いてください。キー workflowSizeGuideline は、v2.1.219以降のどのsettingsファイルでも動きます s1。

settings.json

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

settings.json on GitHub

環境変数の行です。上限2と3。プレースホルダーは、workflowエージェントを動かしたいモデルの完全な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つきで1行ずつにまとめました。

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

キットについて2つの注記です。ultracode キーが意味を持つのは、そうしなければトグルをオンにしてセッションを始めてしまう場合だけで、falseのままにしておけば、ファンアウトは1つのプロンプトで自分が下す判断になります。workflowを完全にオフにすると、キーワードもトグルもなくなります。~/.claude/settings.json に "disableWorkflows": true を設定してください s1。

月曜にやること

  • settings.json をプロジェクトのsettingsにコピーし、/config でサイズの目安がsmallになっていることを確認する。
  • Claude Codeを起動するシェルで ultracode-caps.sh をsourceし、プレースホルダーを本物のモデルidに置き換える。
  • /effort でultracodeのトグルがオフであることを確認し、ファンアウトしたいときは1つのプロンプトでキーワードを使う。
  • ファンアウトの前に、when-to-fan-out.md の2つの質問に答える。1つでも答えがnoなら、highで普通に走らせる。
  • まず一部で走らせ、仕事を広げる前に /workflows でトークン合計を読む。
  • プロンプトに予算を足す。たとえば「use 10k tokens」。
  • 最初の実行では /workflows を開いたままにし、エージェント数が予想を超えて増えたら x を押す。
  • 実行のあと、/usage を開いて、workflowに回った割合を控える。

さらに深く

モデルにワーカーとゲートを書かせず、自分で固定する。 あるHacker Newsの投稿は、workflowの実行と監視のトークン消費を元の約20%に抑え、5〜6時間かかっていたworkflowが今は20〜40分になったと報告しています。自己申告で、プランは明記されていません s6。方法は2つの部分から成ります。workflow-worker のエージェントファイルは、計画の1つの部分と、自分の担当分のテストだけを書いて実行できる厳しい権限を受け取ります。workflow-gate のエージェントファイルは、並列エージェントの結果を受け取り、直列のチェックは2つのターゲットを持つMakefileに移ります。make workflow-serial-gate はgitツリーを確認して変更分のテストを走らせ、make workflow-final-gate はすべてのクリーンなテストを走らせます s6。複雑な計画で10分かかっていたゲートのチェックは、同じ投稿によれば今は1秒です。20%は実行と監視の分で、計画の作成や実装は含みません。試すなら、2つのエージェントファイルを一度書いてリポジトリに置き、workflowのプロンプトからそれを指してください。

生成されたスクリプトを信用する前に、暴走の報告を読む。 そのissueには、フェーズごとの表と、189の余分なエージェントの背後にある1つのパターンが載っています。mergeエージェントが何も返さないと、スクリプトは生のリストにフォールバックして続けるのです s7。失敗したエージェントでスクリプトが止まるよう、モデルに頼んでください。目を離す実行では、auto-continueをオフにしておいてください。

目安が負ける理由を知る。 issue 92631には、目安のテキストとultracodeの一文が並んで示されていて、両者が食い違ったときに後者が勝つ理由が分かります s8。ハードな上限が欲しいなら、同時実行の変数が同時に動くエージェント数を制限し、プロンプトの予算が使う量を制限します。

広い仕事にはローンチのスレッドを使う。 初日の最も鋭い反論はローンチのスレッドにあり、「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個のバグのテストはManaged Agentsの動的workflowを使っており、これはAPI専用です。APIで作るなら、Anthropicが勧めるように、範囲を絞ったタスクから始めてください。Claude Code用の設定は引き継がれません s24。

信用してはいけないもの。 プランも数字もない枠の逸話は又聞きです。あるコメント投稿者は、6つのエージェントが4時間分の枠を食ったと報告し、別の投稿者は、他社の安いモデルで、自分のクローンを通して、ほぼ20億トークンの移植が20ドルで済んだと報告しています s23 s9。どちらも、プラン上のClaude Codeの測定ではありません。数字をメモに残すのは、プラン、モデル、バージョン、タスクが一緒に付いているときだけにしてください。

FAQ

キーワードはトグルと同じだけコストがかかりますか? いいえ。キーワードは1つのタスクをworkflowとして走らせます。トグルはすべての実質的なタスクでworkflowを計画するので、1つの依頼が複数になることがあります s1。どちらも会話の上に上乗せで消費します。各エージェントが自分のリクエストを送るからです s5。

サイズの目安をsmallにすれば、実行は4エージェントまでに制限されますか? いいえ。それはモデルに送られる助言で、プロンプトやultracodeの一文が上書きできます s1 s8。私たちの実行では「5未満」と示されていたのに、実行は9を使いました。ハードな制限は、同時実行の変数と、あなた自身の停止です。

実行がusage limitに達するとどうなりますか? autoContinueAtUsageLimit がオンだと、インタラクティブなclaude.aiセッションは実行を一時停止し、リセットで続けます。待機は最大2回で、v2.1.271からです。それ以前のバージョンは、影響を受けたエージェントを失敗させます s1。オフだと、エージェントは上限で失敗し、実行はそこで終わります。

workflowのエージェントになぜ安いモデルを使うのですか? workflowの大半は確認で、各エージェントが自分のリクエストを送ります。CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL はすべてのworkflowエージェントを1つのモデルに載せ、他のサブエージェントには触れません s18。頼りにする前に、一部で結果を確かめてください。

それでもultracodeを使えますか? はい。チェックリストの2つの質問の両方に通る仕事なら使えます。Bunの移植には、判定役として完全なテストスイートがありました s19。小さな機能やバグ修正なら、highでの通常実行がデフォルトです。

ファイル