Claude Code effortレベルの使い方と設定
effortレベルはClaude Codeの推論の深さを決める設定です。モデルごとに使えるレベルが違い、ultracodeはeffortレベルではなく動的ワークフローを伴う別設定です。非対話モードでのhold挙動もあわせて解説します。
effortレベルは、Claude Codeがタスクごとにどれだけ深く推論するかを決める設定です。low / medium / high / xhigh / maxの5段階があり、使えるレベルはモデルによって異なります。既定値は多くのモデルでhighですが、Opus 4.7だけxhighが既定です。ultracodeはeffortレベルではなくClaude Code独自の設定で、xhighの推論に加えて動的ワークフローによるオーケストレーションが働きます。
effortレベルとは何を制御するか
effortレベルは公式ドキュメントで「adaptive reasoning、各ステップでモデルが考えるかどうかとどれだけ考えるかをタスクの複雑さに応じて判断させる仕組み」を制御すると説明されています。低いeffortは単純なタスクを高速・低コストにこなし、高いeffortは複雑な問題により深い推論を割り当てます。
利用できるレベルはモデルごとに固定されています。
| モデル | 使えるレベル |
|---|---|
| Fable 5 | 使えるレベルlow / medium / high / xhigh / max |
| Opus 5、Sonnet 5、Opus 4.8、Opus 4.7 | 使えるレベルlow / medium / high / xhigh / max |
| Opus 4.6、Sonnet 4.6 | 使えるレベルlow / medium / high / max(xhighなし) |
対応していないレベルを指定すると、Claude Codeは指定値以下でモデルが対応する最も高いレベルにフォールバックします。たとえばOpus 4.6でxhighを指定するとhighとして動作します。組織側でモデルごとの上限を設定することもでき、その場合/effortのメニューには上限を超えるレベルが表示されません。
既定値とモデルごとのhold挙動
既定のeffortは、対応するすべてのモデルでhighです。唯一の例外がOpus 4.7で、既定はxhighになります(Opus 4.7 xhighの挙動とコスト試算は別記事で詳しく扱っています)。
Fable 5・Opus 4.8・Opus 4.7を初めて実行すると、別のモデルで以前設定していたレベルがあってもそのモデルの既定値が適用されます。/effortをインタラクティブに実行するか--effortで起動するといった明示的な選択をするまで、この既定値はセッションをまたいで保持され続けます。Opus 5にはこのhold挙動がなく、以前設定したレベルがそのまま引き継がれます。
low / medium / high / xhighはインタラクティブセッションで設定すると次回以降も引き継がれます。maxは最も深い推論を提供しますが、CLAUDE_CODE_EFFORT_LEVEL環境変数で設定しない限り現在のセッション限りです。
レベルごとの向き不向き
各レベルはトークン消費と能力のトレードオフです。既定値はほとんどのコーディングタスクに適していて、異なるバランスが欲しいときだけ調整します。
| レベル | 向いている場面 |
|---|---|
| low | 向いている場面範囲が狭く、速さが要る単純作業 |
| medium | 向いている場面コストを抑えたい、多少の精度低下を許容できる作業 |
| high | 向いている場面トークン消費と精度のバランスが取れた既定値(Opus 4.7以外) |
| xhigh | 向いている場面より深い推論をトークン消費増と引き換えに得る。Opus 4.7の既定値 |
| max | 向いている場面難しいタスクで効果が出ることがあるが過剰思考になりやすく、広く採用する前に検証が必要 |
effortの尺度はモデルごとに較正されているため、同じレベル名でもモデルが変われば実際の推論量は変わります。high同士でモデルを比較しても、内部で割り当てられる推論の深さは同一ではありません。なおultracodeはこの表のレベルの一つではなく、次の節で扱う別設定です。
ultracodeはeffortレベルではない
/effortのメニューにはultracodeという選択肢もありますが、これは特定のeffortレベルではなくClaude Code独自の設定です。ultracodeを有効にすると、モデルにはxhighが送られ、加えてClaude Codeがまとまった規模のタスクごとに動的ワークフローをオーケストレーションします。適用範囲は現在のセッションのみです。
ultracodeを有効にする方法は3通りあります。
/effort ultracodeを実行するか、メニューから選択するclaude --effort ultracodeで起動する(セッションをxhigh効果レベルかつultracode有効な状態で開始)--settingsまたはAgent SDKの制御リクエストで"ultracode": trueを渡す
--effortフラグやAgent SDKのeffortLevel値にultracodeを渡すにはClaude Code v2.1.203以降が必要です。それより前のバージョンでは--effort ultracodeはUnknown --effort value 'ultracode'と表示され、セッションは既定のeffortで開始されていました。
永続化されるeffortLevel設定やCLAUDE_CODE_EFFORT_LEVEL環境変数はultracodeを受け付けません。CLAUDE_CODE_EFFORT_LEVELがxhigh以外の値に設定されている場合、リクエストはそのレベルで実行され、ultracodeのワークフローオーケストレーションは動作しません。ワークフロー機能自体が無効化されている環境などultracodeが使えない場合、--effort ultracodeが設定するのはxhigh効果レベルのみになります。
非対話モード(-p)でのhold挙動という実務的な注意点
非対話モード(-pフラグ)で/effortを実行した場合、設定は現在のセッションのみに適用され、既定値として保存されません。
ここで実務上つまずきやすいのが、モデルデフォルトのholdを/effortでは解除できないという挙動です。Fable 5・Opus 4.8・Opus 4.7を初めて実行した直後は、そのモデルの既定effortがholdされた状態になります。このholdが効いている間、非対話モードでの/effortはNot applied(適用されませんでした)と報告されるだけで、指定したレベルは反映されません。holdを解除してレベルを変えたい場合は、起動時に--effortフラグを渡します。
CIやバッチ処理など-pで自動実行するパイプラインでeffortレベルを制御したい場合は、この挙動を踏まえて--effortフラグを起動コマンドに含めておく設計が実務的です。/effortを実行結果に頼る設計にすると、hold中は黙って無視される点に注意します。
CLIフラグ・環境変数・設定ファイルでの指定方法
effortレベルの設定手段は複数あり、優先順位が決まっています。
/effort: 引数なしでインタラクティブなスライダーを開く、レベル名を指定して直接設定する、/effort autoでモデルの既定値にリセットする/model内: モデル選択時に左右矢印キーでeffortスライダーを調整する--effortフラグ: 起動時にレベル名を渡し、そのセッション限定で設定する(claude --effort high)- 環境変数:
CLAUDE_CODE_EFFORT_LEVELにレベル名またはautoを設定する - 設定ファイル:
effortLevelにlow/medium/high/xhighのいずれかを設定する(maxとultracodeはセッション限定のため設定ファイルでは受け付けない) - SkillやSubagentのfrontmatter:
effortキーで、そのSkillやSubagentが動いている間だけセッションのeffortレベルを上書きする(Claude Code Sub-agents完全ガイドではfrontmatterで設定できる項目全体を扱っています)
優先順位は、環境変数が他のすべての設定方法に優先し、次に設定済みのレベル、最後にモデルの既定値という順です。SkillやSubagentのfrontmatterによるeffort指定は、そのSkillやSubagentが動作している間セッションレベルを上書きしますが、環境変数は上書きできません。管理設定(managed settings)のeffortLevelはあくまで初期値で、ユーザーはセッション中に/effortや--effortで変更でき、新しいセッションでは管理値が既定として再適用されます。
固定思考量モードとの関係
Fable 5・Sonnet 5・Opus 4.7以降のモデルは常にadaptive reasoning(タスクごとに考えるかどうかを判断する方式)で動作し、effortレベルが推論量を決める主な手段になります。一方Opus 4.6・Sonnet 4.6では、CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1を設定することで、以前の固定思考量モードに戻すこともできます。この場合、思考量はMAX_THINKING_TOKENSで直接制御する形に切り替わり、effortレベルによる自動調整とは別の運用になります。
adaptive reasoning自体は「毎ステップで考えるかどうかを任意にする」仕組みなので、日常的なプロンプトには素早く応答しつつ、深い思考が有効なステップにだけ推論を割けます。現在のeffortレベルが生む思考頻度が想定と違う場合は、プロンプトやCLAUDE.mdで直接「もっと考えて」「即答して」のように指示すると、そのeffort設定の範囲内でモデルが応答を調整します。
よくあるつまずき
xhighを指定したのに反映されない: モデルがxhighに対応していない可能性があります。Opus 4.6・Sonnet 4.6はxhighをサポートせず、指定するとhighにフォールバックします-pで/effortを実行してもレベルが変わらない: Fable 5・Opus 4.8・Opus 4.7を初回実行した直後はモデルデフォルトのholdが効いています。非対話モードの/effortはholdを解除できないためNot appliedになります。起動時に--effortを渡しますultracodeを設定ファイルに書こうとしてエラーになる:effortLevel設定ファイルのキーはultracodeを受け付けません。セッションごとに/effort ultracodeや--effort ultracodeで指定しますmaxが次のセッションで消えている:maxはCLAUDE_CODE_EFFORT_LEVEL環境変数で設定しない限りセッション限定です。永続化するには環境変数を使います
よくある質問
effortレベルを上げるとコストはどれくらい増えますか
具体的な倍率は公式に数値化されていませんが、レベルが上がるほどモデルがより多くの推論トークンを消費する設計です。maxは特に過剰に考え込んで見返りが伸び悩むことがあると公式に説明されており、広く採用する前に対象タスクで効果を検証することが推奨されています。
ultrathinkとeffortレベルは同じものですか
別物です。プロンプトのどこかにultrathinkという語を含めると、そのターンだけ深い推論を要求できます。これはセッションのeffort設定を変えるものではなく、APIに送られるeffortレベル自体は変化しません。thinkやthink hardのような他の言い回しはキーワードとして認識されず、通常のプロンプトの一部として扱われます。
effortレベルはSubagentごとに変えられますか
変えられます。Subagentのfrontmatterにeffortキーを設定すると、そのSubagentが動いている間だけセッションのeffortレベルを上書きします。値はlow / medium / high / xhigh / maxのいずれかで、利用できる範囲はそのSubagentが使うモデルに依存します。Skillのfrontmatterでも同じ仕組みが使えます。
まとめ
effortレベルはClaude Codeの推論の深さを決める設定で、lowからmaxまで5段階あり、対応レベルはモデルごとに異なります。既定はhigh(Opus 4.7のみxhigh)で、Fable 5・Opus 4.8・Opus 4.7は初回実行時にモデルデフォルトのholdがかかります。ultracodeはeffortレベルではなく、xhighの推論と動的ワークフローのオーケストレーションを組み合わせたセッション限定の設定です。非対話モード(-p)では/effortがhold中にNot appliedと報告されるだけで反映されないため、自動実行パイプラインでは起動時の--effortフラグを使います。