Claude Codeのeffort設定はどれが優先されるか：CLAUDE_CODE_EFFORT_LEVEL、--effort、modelSettings、effortLevel、maxEffortLevelの順位

Claude Codeのeffort設定は複数の場所に散らばっている。effortLevel、modelSettings、maxEffortLevel、--effort、環境変数CLAUDE_CODE_EFFORT_LEVEL、/effortコマンド、ultrathinkキーワードだ。複数が同時にあるとき、どれが優先されるのか。本稿は公式の設定リファレンスから優先順位を整理する。私が読んだページは一部が途切れていたため、読めた部分だけを書き、読めなかった部分はそう記した。どの組み合わせも検証していない。

優先順位（高い順）

1. CLAUDE_CODE_EFFORT_LEVEL：ドキュメントによれば--effortとeffortLevelの両方より優先される。受け付ける値は読めなかった。
2. --effort：1セッションのみで、effortLevelキーより優先される。
3. 同じ設定ファイル内では、modelSettings配下のモデルのeffortLevelが、最上位のeffortLevelより優先される。
4. 最上位のeffortLevel：文字列で、読めた値はlow、medium、high、xhigh、既定は未設定。レベルを保存していないモデルの既定値を設定する。

これらすべての上に上限がある。maxEffortLevel（v2.1.267以降）だ。ドキュメントによれば、セッションが使えるeffortに上限をかけ、/effort、/modelピッカー、--effort、CLAUDE_CODE_EFFORT_LEVELからのものを含め、それより高いレベルは上限で実行される。値はlowからmaxで、maxは上限なしを意味する。modelSettings配下でモデルごとの上限も設定できる。

/effortが実際に書き込む場所

• 自分のマシンの対話型セッションで/effort low、medium、high、xhighを実行すると、Claude Codeは最上位のeffortLevelではなく、現在のモデルのmodelSettings配下にレベルを保存する。v2.1.251より前は、/effortが最上位のキーに書いていた。
• リモートワーカーに接続したセッション、-p実行、Agent SDKでは、/effortはそのセッションのみに適用される。
• /effort autoは、使用中のモデルに保存したレベルを消去する。

はまりやすい3つの落とし穴

• ユーザー設定のeffortLevelは新しいモデルに効かない：ドキュメントによれば、~/.claude/settings.jsonではこのキーは、/effortがモデルごとにレベルを保存する前に書いていた旧形式で、Opus 5、Fable 5.1、それ以前のモデルには引き続き適用される。Opus 5.5とそれ以降のモデルはこれを無視し、レベルを保存するまで自身の既定値で始まる。プロジェクト、ローカル、managed設定、--settingsでは、このキーはすべてのモデルに適用される。これで「ユーザー設定にxhighと書いたのに、なぜOpus 5.5で使われないのか」に明確な答えが出る。
• 上限は明示的な指定より優先される：maxEffortLevel: "medium"を設定すると、--effort xhighでもmediumで実行される。
• thinkingをオフにする組み合わせ：ドキュメントによれば、Anthropic APIでthinkingをオフにすると、Claude Codeはその組み合わせを受け付けないと知っているモデル（Opus 5など）には、より高いレベルではなくeffort highを送る。常に考えるモデル（Opus 5.5、Sonnet 5.5、Haiku 5.5、Fableモデル）では、thinkingをfalseにしても効果がない。

ultracodeとultrathink

混同しやすい2つだ。ultracode（設定ページにあるキー）は、Claudeが実質的なタスクごとに指示なしでワークフローを計画する機能で、ドキュメントによれば、動的ワークフローが有効で、モデルがxhighに対応している場合にのみ計画する。セッションのeffortは変えず、セッションの現在のレベルで動く。/effort ultracodeは現在のセッションのみ、--effort ultracodeも1セッションのみでxhighで有効になる。v2.1.284より前はultracode: trueでセッションがxhighで動き、xhigh未満の上限ではultracodeがオフになっていた。ultrathinkはプロンプト内のキーワードで、v2.1.311のリリースノートによれば、対話型ターミナルでAnthropic API経由のOpus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1を使うとき、そのターンがxhigh effortで実行され、Claudeの作業中に入力するとターンの残りが引き上げられる。私が読んだ設定ページにはultrathinkの語がないので、ここでの挙動はリリースノートのみが根拠だ。またmaxEffortLevelの上限がultrathinkも制限するかは、読んだ範囲では見つからなかったので、仮定しないこと。

私の判断：混乱せずに設定するには

以下は私の整理で、公式の助言ではない。個人の好みには/effortを使う（モデルごとの枠に保存される）。チーム全体の上限はmanagedまたはプロジェクト設定のmaxEffortLevelに置く。明示的な指定さえ上書きするからだ。CIや定期タスクには最優先のCLAUDE_CODE_EFFORT_LEVELか--effortを使う。ユーザー設定に最上位のeffortLevelを手書きして新しいモデルにも効くと期待するのは避ける。コストについて、ドキュメントが述べるのは、低いレベルは単純なタスクでより速く安く、高いレベルは複雑な問題でより深く推論するということだけで、公式ページにレベルごとのコスト比はなく、私も数字を持っていない。