Claude Codeのeffort上限 — role別の上限とmaxEffortLevelはどちらが効くか

組織がClaude Codeのeffortに上限をかける方法は2つあります。Claude Enterpriseの管理者がロールごと・モデルごとに決める上限と、managed settingsに書くmaxEffortLevelです。両方が同じモデルに効く場合は、低い方の上限が適用されます。

この記事は、管理者がどちらを使うか決めるときと、開発者が「/effortにxhighが出てこない」と気づいたときの両方を想定して、2つの上限の関係をまとめます。個人がeffortを選ぶ基本はClaude Codeのeffort(エフォートレベル)とはにあります。

組織がeffortに上限をかける2つの方法

違いは、上限を決める場所です。前者は管理コンソールのロール設定で、後者は設定ファイルです。Enterpriseでないプランや、サードパーティのプロバイダー経由で使う組織は、設定ファイル側のmaxEffortLevelだけが選択肢になります。

maxEffortLevelの追加はv2.1.267のリリースで入りました。その回の全体像はClaude Code v2.1.267のリリースノートにまとめています。

併用したときは低い方が適用される

同じモデルに両方の上限が効くとき、ルールは1行です。低い方の上限が適用されます。

ただし、上限が決まるまでに通る段が複数あります。段ごとのルールは次のとおりです。

ロールの段だけ向きが逆です。ロールの中では「緩い方」、ロールとmaxEffortLevelの間では「低い方」が勝ちます。

次の計算例で確かめます。数値は説明のために置いたもので、実在する設定ではありません。

ロールBだけに属するメンバーでmaxEffortLevelが"max"なら、上限はxhighのままです。"max"は上限をかけない値だからです。

上限に当たったとき、画面と出力はどう変わるか

上限は「エラーで止める」のではなく「上限のレベルで動かす」仕組みです。挙動は、レベルの選び方と実行形態で少しずつ違います。

• /effortのピッカー(スライダー)には、上限を超えるレベルが表示されません
• --effortや/effortで上限より高いレベルを指定しても、上限のレベルで実行されます
• プレーンテキスト出力の--print実行で、上限を超える--effortを付けると、要求したレベルと実際に適用したレベルを示す警告がstderrに出ます
• 対話セッション、json・stream-json出力、バックグラウンドエージェントでは、同じ警告がデバッグログに回ります

CIでclaude -pを回しているチームは、最後の2項目に注意が必要です。stderrに警告が出るのはプレーンテキスト出力のときだけです。--output-format jsonで結果を機械処理している場合、警告はデバッグログに回り、stderrには出ません。上限が効いているか確かめたいときは、claude --debugで起動してデバッグログを見ます。

上限はモデルごとに決まります。モデルを切り替えると、選べるレベルの範囲も変わります。たとえばあるモデルには上限があり、別のモデルには上限がない、という状態になりえます。

上限が効く経路と効かない経路

maxEffortLevelは、effortが決まるあらゆる経路に対してクライアントがリクエストの前に適用します。

最後の行が見落とされやすい点です。managed settingsにeffortLevelを書くだけでは、ユーザーの選択を止められません。設定ステップの既定値になるだけで、/effortや--effortで変更できます。レベルを上限で縛りたいときはmaxEffortLevelを使います。

サブエージェントにeffortを指定している構成でも、上限は越えられません。frontmatterの指定方法はサブエージェントをeffort指定で走らせる方法で扱っています。

ultracodeとの関係

/effortスライダーのUltracodeはeffortレベルではなく、動的ワークフローを組むための設定です。上限があっても、ultracodeはその上限のレベルでオンのまま動きます。v2.1.284より前は、xhigh未満の上限がかかるとultracodeが使えませんでした。細部はClaude Codeのultracode設定にあります。

管理者向け: maxEffortLevelの書き方

設定ファイルには、全モデルへの上限をトップレベルに、モデル別の上限をmodelSettingsの中に書きます。全モデルをmediumで止めつつ、Sonnet 4.6だけを上限の対象から外す設定は次のとおりです。

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

型は"low"・"medium"・"high"・"xhigh"・"max"の文字列で、既定は未設定(上限なし)です。

「max」で外せる範囲には限りがある

モデル別のmaxEffortLevelがトップレベルの値を置き換えるのは、同じ設定ソースにどちらも書いたときだけです。たとえばユーザー設定の中、または1つのmanagedソースの中が該当します。

逆に、開発者が自分の設定や--settingsでより低い上限を置くことはできます。管理側の上限より低ければ、その低い方が適用されます。管理者側のどのソースからも、上限を引き上げる手段はありません。複数のmanagedソースがあるときの統合の仕方は、managedSourcesBehaviorで複数の管理設定ソースを統合するで扱っています。

モデルごとのeffortを個人が保存する側の仕組みは、modelSettingsのeffortをモデル別に直接編集するを参照してください。

配布経路の違い

ロール別の上限は、ロール単位のモデル制限と一緒に、同じセッションへ届きます。Bedrock、Agent Platform、Foundryを使う組織は、設定ファイルでmaxEffortLevelを配る方法が用意されています。managed settings全般の配り方はClaude Code組織管理ガイドにあります。

モデルそのものを絞る設定も別にあります。availableModelsとの関係はenforceAvailableModelsでDefaultモデルの抜け穴を塞ぐにまとめました。effortの上限とモデルの許可リストは別の仕組みで、片方を設定してももう片方は制限されません。

「上位のレベルが出ない」ときの切り分け

開発者の側から見ると、症状は「/effortのスライダーにxhighやmaxが出ない」か「指定したのに効いていない気がする」のどちらかです。

セッションのヘッダには、モデル名の隣に「with low effort」のように現在のレベルが表示されます。ピッカーを開かなくても、実際に適用されているレベルを確かめられます。

どちらを使えばよいか

管理者の判断は、契約プランと使うプロバイダーで決まります。

併用するなら、maxEffortLevelを全社共通の天井、ロール別の上限を部署ごとの絞り込みと分けて考えると整理しやすくなります。どちらか低い方が効くので、ロール側を緩めてもmaxEffortLevelを越えることはなく、運用ミスで全社の天井が崩れることもありません。

上位レベルを許すかどうかは、トークン消費の問題でもあります。max effortの警告への対処はmax effortの3.5倍警告が出るときの対処にあります。

まとめ

2つの上限は競合せず、低い方が勝つ仕組みです。ロール別の上限はEnterprise専用で管理コンソールから、maxEffortLevelは全プラン・全プロバイダーで設定ファイルから配ります。

見落としやすいのは3点です。effortLevelをmanaged settingsに書いても縛りにはならないこと。モデル別の"max"は同じソース内の上限しか外せないこと。json出力の--print実行では、上限の警告がstderrに出ないことです。