Ultracode と Effort レベル:思考の深さと Workflow の編成
Claude Code のモデル別5段階の effort レベル、デフォルト、maxEffortLevel と modelSettings、そして独立した workflow 設定である ultracode のオン/オフ方法と、workflow 実行の監視・制限方法を解説。
2026年11月4日更新: Claude Code v2.1.318 に照らして見直しました。メイン会話と異なるモデルで動くサブエージェントとチームメイトは、セッションの effort レベルではなく、そのモデルの保存済みレベルまたはデフォルトを使うようになりました(v2.1.317)。
CLAUDE_CODE_SUBAGENT_EFFORTは、他に指定のないサブエージェントの effort レベルを設定します(v2.1.316)。また、ultrathinkを入力すると 1 ターンをxhighで実行できるようになりました(v2.1.311)。2.1.305 に合わせた10月21日の改訂内容(モデル別の effort 対応表、maxEffortLevel、modelSettings、v2.1.284 以降は独立した設定となった ultracode)は引き続き有効です。
Claude Code の歴史の大半において、大きなダイヤルは 1 つ——どのモデルを使うか——だけでした。今は 2 つ目のダイヤルがあり、日々の作業ではこちらのほうが重要かもしれません。/effort は各ステップでモデルがどれだけ深く推論するかを制御し、現行の Claude モデルはすべてこれに対応しています。Ultracode は独立したスイッチです。 Claude Code の設定であり、追加の effort レベルではありません。セッションが動いている effort レベルのまま、実質的なタスクで動的な workflow をオーケストレーションするよう Claude に指示するものです。
本ガイドでは、5つの effort レベルとモデルごとの対応状況、Claude Code がレベルを決める仕組み、レベルを保存・制限する設定、ultracode が実際に何を変えるのか、workflow 実行を監視・制御する公式の仕組み、そして——同じくらい重要な——何も触らずにおくべき場面を扱います。
Effort が実際に制御するもの
Effort は adaptive reasoning(適応的推論)を方向づけます。モデルは各ステップで考えるかどうか、どれだけ考えるかを自分で決め、effort レベルはその考えやすさを決めます。どのモデルが応答するかは変わりません——それは /model の役割です。変わるのは、そのモデルが行動する前にどれだけ思考を費やすかです。
トレードオフは単純です。
more effort → deeper reasoning per step
→ more tokens, more latency
→ better answers on hard problems
less effort → faster, cheaper turns
→ perfectly fine for mechanical work
このダイヤルを正しく使うための注意点が2つあります。1つ目に、effort の目盛りはモデルごとに調整されているので、同じレベル名でもモデルが違えば思考量は同じではありません。2つ目に、新しいモデルほど各レベルで多くを引き出せます。「Anthropic のテストでは、medium の Opus 5.5 は、コーディングとナレッジワークの評価で high の Opus 5 と同等以上の結果を出した」とされています。Opus 5 から Opus 5.5 に移行するときは、以前のレベルを持ち越さず medium から始めてください。
どのモデルを動かすかも同時に検討しているなら、モデル選択ガイドと合わせて読んでください。モデル階層と effort レベルは別々の 2 つのダイヤルであり、面白い構成は両者の組み合わせから生まれます。
5つのレベル
/effort には low、medium、high、xhigh、max の5つのレベルがあります。Claude Code のドキュメントに沿って、それぞれの使いどころをまとめます。
| レベル | 使いどころ |
|---|---|
| low | 結果を毎回確認する素早いやり取り:ブレインストーミング、最初のたたき台、リネーム |
| medium | Opus 5.5、Sonnet 5.5、Haiku 5.5 のデフォルト。機能の実装など、範囲が明確な日常のエンジニアリング作業 |
| high | 検証が重要な作業やエッジケースがありそうな作業。既存のコードベースでのバグ修正など |
| xhigh | より多くのトークンを使ってより深く推論する:アーキテクチャの意思決定、敵対的検証、「絶対に間違えられない」場面 |
| max | あなたの手を借りずに Claude に解き切ってほしい難問。セキュリティ脆弱性の探索など |
max は効果が逓減することがあり、考えすぎる傾向もあるため、広く採用する前にテストしてください。Anthropic が Opus 5.5 と Fable 5.1 で行ったテストでは、高いレベルほどエッジケースを多くテストし、作業をより多く検証し、自分で下す判断も増えました。低いレベルでは出発点をより早く返し、結果を毎回確認して次の一手を指示する作業に向いていました。
どのモデルがどのレベルに対応するか
Claude Code 2.1.318 に掲載されているレベルとデフォルトは次のとおりです。
| モデル | レベル | Claude Code でのデフォルト |
|---|---|---|
| Fable 5.1、Fable 5 | low、medium、high、xhigh、max | high |
| Opus 5.5、Sonnet 5.5、Haiku 5.5 | low、medium、high、xhigh、max | medium |
| Opus 5(前世代の Opus)、Sonnet 5、Opus 4.8 | low、medium、high、xhigh、max | high |
| Opus 4.7 | low、medium、high、xhigh、max | xhigh |
| Opus 4.6、Sonnet 4.6 | low、medium、high、max | high |
| Haiku 4.5 とその他の未掲載モデル | effort の制御なし | — |
Haiku 5.5 は effort 対応モデルで、effort を調整できる初の Haiku クラスモデルです。一方、Haiku 4.5 は effort 対応モデルとして掲載されていない点に注意してください。Claude Platform on AWS、Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry では今も haiku が Haiku 4.5 に解決されるため、この違いは重要です。現在のモデルが対応していないレベルを指定すると、Claude Code はそれ以下で対応している最も高いレベルにフォールバックするので、xhigh は Opus 4.6 では high として動作します。また、Claude Code でのデフォルト(medium)が Claude API でのデフォルト(high)と異なる現行モデルは Sonnet 5.5 だけです。
モデルの表示とentitlementはprovider、プラン、アカウント、rolloutによって異なるため、現在の環境では /model を確認してください。
Claude Code がレベルを決める仕組み
Claude Code は、次のうち最初に当てはまるものを採用します。
- 明示的な選択:
CLAUDE_CODE_EFFORT_LEVEL環境変数(他の2つより優先)、起動時の--effort、またはセッション内の/effort。 - 設定:
modelSettingsにそのモデル用に保存されたレベル、またはeffortLevelキー。 - モデルのデフォルト: 上の表を参照。Claude Enterprise では、組織のデフォルトモデルに組織がデフォルト effort を設定していれば、そのモデルのデフォルトはそのレベルになります。
選択がどれだけ続くかは、どう設定したかで決まります。
/effort high、または/effortスライダーや/modelピッカーでのEnterは、そのレベルをそのモデルのデフォルトとして、ユーザー設定のmodelSettingsに保存します。- スライダーやピッカーでの
s(v2.1.257 以降)は、現在のセッションだけに適用します。 maxはセッション限定です。CLAUDE_CODE_EFFORT_LEVELで設定した場合を除きます。/effort autoは現在のモデルの保存済みレベルを消去し、/effort statusは有効なレベルを表示します。claude -pの実行、Agent SDK、Remote Control で接続したデバイスからの指定では、レベルはそのセッションだけに適用されます。- 自分で入力したプロンプトに
ultrathinkを含めると、影響するのはそのターンだけです。インタラクティブなターミナル(v2.1.311 以降)と VS Code 拡張機能(v2.1.316 以降)では、Anthropic の API 経由の Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1 でそのターンをxhighで実行でき、保存済みのレベルは変わりません。後述のultracodeキーワードとは関係ありません。
移行時の落とし穴が1つあります。ユーザー設定のトップレベルにある effortLevel は、レベルがモデル単位で保存されるようになる前に /effort が書き込んでいた旧形式です。Opus 5、Fable 5.1、それ以前のモデルには引き続き適用されますが、Opus 5.5 とそれ以降に登場したモデルはこれを無視し、レベルを選ぶまでは自分のデフォルトから始まります。(プロジェクト、ローカル、マネージド設定のトップレベルの effortLevel は、すべてのモデルに適用されます。)
セッションヘッダーには、モデル名の横に現在のレベルが表示されます(例:「with low effort」)。セッション途中で effort を変えると、プロンプトキャッシュを失うこともあります。多くのモデルではレベルごとにキャッシュが分かれているため、キャッシュがまだ有効なうちは Claude Code が確認を求めます。API キーまたは Claude のサブスクリプションで使う Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1 では、変更後もキャッシュが保たれます。それでも、できればセッションの最初にレベルを決めておきましょう。
設定で Effort を保存・制限する
effort に関係する設定キーは3つです。
effortLevel:まだレベルを保存していないモデルのデフォルト。受け付けるのはlow、medium、high、xhighだけで、maxもultracodeも受け付けません。modelSettings(v2.1.251 以降):モデル名をキーにしたモデル単位のエントリーです。各エントリーにはeffortLevel、上限のmaxEffortLevel、autoCompactWindowを持たせられます。/effortがあなたの選択を保存するのはここで、同じファイル内ではモデルのエントリーがトップレベルのeffortLevelより優先されます。maxEffortLevel(v2.1.267 以降):上限です。それより高いレベルは、/effort、--effort、CLAUDE_CODE_EFFORT_LEVEL、スキルやサブエージェントのフロントマター、モデル自身のデフォルトのどこから来たものでも、上限のレベルで動作します。Claude Code は Bedrock、Agent Platform、Foundry を含むすべての provider でこれを強制します。複数の設定ファイルが上限を設定している場合は最も低いものが採用され、"max"は上限なしを意味します。組織全体に強制するには、マネージド設定に配置します。
たとえば次の設定は、Opus 5.5 をデフォルトの medium ではなく high にし、すべてのモデルの上限を xhigh にしたうえで、Fable 5.1 をその上限の対象外にします。
{
"maxEffortLevel": "xhigh",
"modelSettings": {
"claude-opus-5-5": { "effortLevel": "high" },
"claude-fable-5-1": { "maxEffortLevel": "max" }
}
}
より狭い範囲で effort を設定する場所がさらに2つあります。スキルやサブエージェントのフロントマターにある effort フィールドは、そのスキルやサブエージェントの実行中に適用されます。また v2.1.292 以降は、Claude がサブエージェントを生成するときに effort パラメータを渡せます。どちらもセッションのレベルを上書きしますが CLAUDE_CODE_EFFORT_LEVEL は上書きせず、上限も引き続き適用されます。どちらも指定されていないサブエージェントがセッションのレベルで動くのは、メイン会話と同じモデルで動く場合だけです。v2.1.317 以降、異なるモデルで動くサブエージェントとチームメイトは、そのモデルの保存済み effort レベルまたはデフォルトを使います。また v2.1.316 の CHANGELOG では、他に指定がないときにサブエージェントが動くレベルを設定する CLAUDE_CODE_SUBAGENT_EFFORT が追加されました。Claude Enterprise では、管理者がモデルごとにロール別の effort 上限を設定することもでき、組織の上限と maxEffortLevel の両方が適用される場合は低いほうが採用されます。
Ultracode:追加の effort レベルではなく、Workflow の設定
Claude Code v2.1.284 以降、ultracode は独立したトグルになりました。CHANGELOG は一文でこう述べています。「Ultracode を /effort 内の独立したトグル(Tab、または /effort ultracode [on|off])に変更:xhigh effort を強制しなくなり、どの effort レベルでもオンのまま維持される。」
つまり ultracode は Claude Code の設定であり、追加の effort レベルではありません。オンにすると、Claude はあなたに頼まれるのを待たず、実質的なタスクごとに動的な workflowを計画します。しかもセッションの現在の effort レベルのままです。Claude は最速でも最安でもなく最も網羅的で正確な回答を目指すよう指示され、1つのリクエストが連続した複数の workflow になることもあります。コードを理解するもの、変更を加えるもの、検証するものです。そのため、セッション内のすべてのタスクがより多くのトークンと時間を使います。サブスクリプションプランではそのトークンが利用上限に計上されるので、ultracode をオフにしている場合より早くセッションや週次の上限に達します。
ultracode をオンにすることは大規模な実行への同意でもあるため、オンの間は次の3つのチェックが外れます。
- Large workflow 警告が表示されません。
- Claude が Agent ツールで生成するサブエージェントには、セッションの同時実行サブエージェント数の上限が適用されません。
- auto パーミッションモードでは、最初の workflow 起動時に承認を求められません。
ultracode を使えるのは、動的な workflow が有効になっていて、現在のモデルが xhigh に対応している場合だけです。そのため Opus 4.6、Sonnet 4.6、Haiku 4.5 などのモデルでは使えません。動的な workflow はすべての有料プラン、Anthropic API を使う場合、そして Bedrock、Agent Platform、Foundry で利用できます。Pro プランでは、まず /config の Dynamic workflows の行でオンにしてください。
v2.1.284 より前の動作は異なっていました。ultracode をオンにするとセッションが xhigh になり、別のレベルを選ぶとオフになり、xhigh 未満の effort 上限があると利用できませんでした。古いガイド(この記事の以前の版を含む)が説明しているのは、その動作です。
オンとオフの切り替え方
| 方法 | 範囲 | effort レベルへの影響 |
|---|---|---|
/effort ultracode(または /effort ultracode on) | 現在のセッション | 変わらない |
/effort ultracode off | 現在のセッション | 変わらない |
/effort スライダーで Tab、続けて Enter | 現在のセッション | 変わらない |
claude --effort ultracode | 起動したセッション | xhigh に設定 |
設定ファイルまたは --settings の "ultracode": true | それを読み込むすべてのセッション | 変わらない |
Agent SDK の applyFlagSettings() で effortLevel: "ultracode" | そのセッション | xhigh に設定 |
永続化する方法は、普通の設定キーです。
{
"ultracode": true
}
Claude Code はこのキーを読み込みますが、書き込むことはありません。/effort ultracode は現在のセッションにしか影響しないからです。また、このキーが true でも、/effort ultracode off でそのセッションだけ ultracode をオフにできます。永続化される effortLevel 設定と CLAUDE_CODE_EFFORT_LEVEL は ultracode を受け付けません。これらのいずれか、あるいは effort の上限がセッションのレベルを決めている場合、ultracode はそのレベルのままオンになります。/effort スライダーや /model ピッカーでレベルを選んでも、ultracode の状態は変わりません。--effort ultracode フラグには v2.1.203 以降が必要で、off の形式、スライダーのトグル、xhigh 以外のレベルでオンを維持する動作には v2.1.284 以降が必要です。
キーワード:1つのタスクだけ、セッションは変えない
セッションの設定を変えずに1つのタスクだけを workflow として実行するには、プロンプトにキーワード ultracode を含めます。
ultracode: audit the payments module for correctness bugs
Claude Code はキーワードをハイライトし、Claude はそのタスクをターンごとに進める代わりに workflow スクリプトを書きます。自分の言葉で頼む(「ワークフローを使って…」)方法でも構いません。キーワードが決めるのは作業の構成方法だけで、エージェントのツール呼び出しには他のツール呼び出しと同じパーミッションチェックとサンドボックスが適用されます。有効なのは自分で入力したプロンプトだけなので、claude -p のプロンプト、スケジュールされたタスク、セッションに転送された webhook ペイロードや pull request のコメントでは発動しません。意図しないハイライトは Option+W(macOS)または Alt+W(Windows/Linux)で解除でき、/config の Ultracode keyword trigger("workflowKeywordTriggerEnabled": false)でトリガー自体をオフにできます。
workflow は、組み込みの /deep-research や以前の実行から保存したコマンドなど、workflow コマンドを呼び出したときにも実行されます。これらのオプトイン——ultracode、キーワード、明示的な依頼、workflow コマンド——のいずれもなければ、Claude は個別のサブエージェントか単独で作業します。大規模なオーケストレーションは、常にあなたが自ら求めたものなのです。
Workflow 実行の監視と制限
Ultracode はより多くのオーケストレーションへのオプトインであり、固定費用の保証ではありません。公式の管理手段は運用上のものです。
- 監視:
/workflowsは実行中と完了済みの run を一覧表示し、各 run の進捗ビューにはフェーズ、エージェント、エージェント別のトークン使用量が表示されます。pで一時停止/再開、xで選択したエージェントまたは run 全体を停止、rで実行中のエージェントを再起動、sでスクリプトを再利用可能なコマンドとして保存します。入力欄の下のタスクパネルにも1行の進捗サマリーが表示されます。 - 警告: run が 25 を超えるエージェントをスケジュールするか、予測トークン総数が 150 万を超えると、Large workflow 警告が表示されます。あくまで助言であり、ultracode がオンのセッションでは表示されません。
- 規模の目安:
/configの Dynamic workflow size 設定(またはworkflowSizeGuidelineキー)は、エージェント数を 5 未満(small)、10 未満(medium)、50 未満(large)に収めるよう Claude に求めるか、規模を Claude に任せます(unrestricted)。デフォルトはmediumで、v2.1.271 以降の Pro プランではsmallです。これは Claude への助言であり、上限ではありません。 - ハードリミット: ランタイムはデフォルトで最大 16 エージェントを同時実行し(CPU の少ないマシンではそれより少なく、
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSは v2.1.269 以降で 1〜256 を受け付けます)、1回のparallel()またはpipeline()呼び出しで 4,096 件を超える項目を拒否し、1回の run で合計 1,000 エージェントまでとしています。 - 利用上限: claude.ai のサブスクリプションでサインインしたインタラクティブセッションでは、利用上限に達したエージェントは失敗せず、上限がリセットされるまで run を一時停止させます(v2.1.271 以降、
autoContinueAtUsageLimitがオンの場合)。 - モデルのコスト: workflow エージェントはサブエージェントと同じ順序でモデルを決め、指定がなければセッションのモデルで動作します。
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL(v2.1.296 以降)を使えば、すべての workflow エージェントを1つのモデルで動かせます。 - オフにする方法:
/effort ultracode offで常時のオプトインを終えられます。workflow 自体を(ultracode ごと)無効にするには、/configで Dynamic workflows をオフにするか、"disableWorkflows": trueを設定するか、CLAUDE_CODE_DISABLE_WORKFLOWS=1を設定します。effort の上限は ultracode セッションの動作レベルを下げますが、ultracode をオフにはしません。
高コストなタスクは 1 ディレクトリや狭い問いから始め、結果とトークン使用量を確認してから意図的に拡大してください。
エージェント単位の Effort:判断が生きる場所に投資する
ワークフロースクリプトの内部では、effort はサブエージェント単位で設定します:effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max'。大規模実行の経済性が実際に決まるのはここです。パターンはこうなります。
- 安価で機械的なステージ(検索、読み取り、整形)→ effort 対応モデルなら
low、または Haiku を effort 上書きなしで - 難しい検証・判定ステージ →
highまたはxhigh
以下は、この 2 つの考え方を組み合わせた停止条件付きの発見ループです——安価なファインダーが 2 回連続で新規発見を得られなければ停止し、その後、見つかったものすべてに高価なスケプティックを投入します。(ワークフロースクリプトは、name、description、phases を宣言する export const meta = { ... } リテラルで始まります。以下の断片は本体部分です。)
phase('Discover');
let dryRounds = 0;
const seen = [];
while (dryRounds < 2) {
const round = await parallel([
() => agent(
`Hunt for correctness bugs in the payments module.
Already seen: ${seen.join('; ') || 'none'}.
Report only NEW findings, or the word NONE.`,
{ label: 'hunt-correctness', model: 'haiku' }
),
() => agent(
`Hunt for error-handling gaps in the payments module.
Already seen: ${seen.join('; ') || 'none'}.
Report only NEW findings, or the word NONE.`,
{ label: 'hunt-errors', model: 'haiku' }
),
]);
const fresh = round.filter(Boolean).filter(r => !r.trim().startsWith('NONE'));
if (fresh.length === 0) dryRounds += 1;
else { dryRounds = 0; seen.push(...fresh); }
}
phase('Verify');
const verdicts = await parallel(
seen.map(finding => () => agent(
`Try to REFUTE this finding. Confirm only if you cannot:
${finding}`,
{ label: 'skeptic', effort: 'xhigh' }
))
);
支出の形に注目してください。何ラウンドも回る可能性のあるループは Haiku を effort 上書きなしで使い、xhigh は、誤った判定が実際に高くつく検証ステージのために温存されています。haiku のステージに effort を付けないのは意図的です。haiku は Anthropic API では Haiku 5.5 ですが、Bedrock、Agent Platform、Foundry、Claude Platform on AWS では Haiku 4.5 なので、こうしておけばどの provider でもスクリプトが正しく動きます。ファインダーには既出の発見が伝えられるので、古い発見を焼き直して売り込むことはありません。そしてループは、空のラウンドが 2 回連続して初めて停止します——effort と ultracode のチュートリアルとその姉妹編(品質パターン)で詳しく扱われている「loop-until-dry」パターンです。
Ultracode を使うべきでない場面
強力なスイッチの失敗モードは、オンにしっぱなしにすることです。次の場面では ultracode を避けてください。
- 些細な編集。 リネーム、タイポ修正、設定の微調整に必要なのは 1 つのエージェントと低い effort です。そのためにオーケストレーションされたワークフローを立ち上げるのは純粋な無駄です。
- 会話的なターン。 「この関数は何をする?」「どちらのアプローチが好み?」はコンテキストから答えられます。ファンアウトするものが何もありません。
- 単一の事実の参照。 答えがどのファイルにあるか分かっているなら、直接読むほうがどんな委譲にも勝ります。
- 高速なイテレーションを求めるすべての作業。 ultracode は網羅性と正確性に最適化しますが、それはまだスケッチ段階にいるときの素早いフィードバックループとは正反対のものです。
経験則:ultracode は、見落としが高くつき、探索空間が 1 つのエージェントのコンテキストより大きいタスクのためのものです。それ以外はすべて、ultracode なしのほうがうまく——そして劇的に安く——動きます。通常の作業に戻るときは /effort ultracode off を実行しましょう。コスト全体の視点はコスト最適化のチュートリアルを参照してください。
3 つのレシピ
監査。 ultracode: audit the auth module for security issues. これは ultracode のホームグラウンドです。まず範囲を区切り、上の loop-until-dry の形を使い、すべての発見を敵対的に検証し、カバレッジ上の制約を明記します。
移行。 ultracode: migrate every deprecated API call in src/ to the new client. ファイルを並列に変更するエージェントには、agent() 呼び出しに isolation: 'worktree' が必要です。各エージェントが新しい git worktree を受け取るので互いを踏み荒らすことがなく、変更がなければ自動的に削除されます。worktree はエージェントごとに実際のセットアップ時間とディスクを消費します——まさに、あのキーワードを打ち込むときにあなたが同意している規模です。
リサーチスイープ。 ultracode: map every place we handle currency rounding, and how. マルチモーダルなスイープ(一斉探索)です。並列エージェントがそれぞれ異なる方法で検索し(ファイルの場所で、内容で、エンティティで、時間で)、その後に「何が欠けている?」と問う網羅性クリティックの回答が次のラウンドの種になります。スイープは Haiku に effort 上書きなしで任せ、高価な処遇は最終的な統合のために取っておきます。
持ち帰るべきこと
Effort は回答の品質をタスク単位で制御できるものにしました。Claude Code 2.1.318 では Haiku 5.5 を含むすべての現行モデルがダイヤル全体に対応し、5.5 ファミリーのデフォルトは medium、Fable 5.1 のデフォルトは high です。modelSettings はモデルごとにレベルを記憶し、maxEffortLevel はすべての provider で上限を設けます。Ultracode は別の設定です。各ステップでどれだけ深く考えるかではなく、Claude が workflow をオーケストレーションするかどうかを決めるもので、/effort ultracode off を実行するまで、どのレベルを選んでもオンのまま維持されます。コスト管理はスコープ、規模の目安、ライブ可視性、ランタイムのエージェント上限、そして run を停止する能力によって行います。
身につける価値のあるスキルは「常に ultracode を使う」ことではありません。自分のタスクのうち、どれが ultracode に値するのかを見分けることです。監査、移行、リサーチスイープには「はい」。いま直そうとしているタイポには「いいえ」。
さらに深く知りたい方へ。Effort レベルと Ultracode のチュートリアルでは各種の管理手段を実際に試しながら学べ、Workflow とは何か?では ultracode の土台となるオーケストレーション層を解説しています。