Claudeのeffortとは?考える量を5段階で決める設定

Claudeのeffortとは?考える量を5段階で決める設定

2026年10月31日に出た Claude Code 2.1.316 に、CLAUDE_CODE_SUBAGENT_EFFORT という環境変数が加わりました。

サブエージェントがどの effort で動くかを、親のセッションとは別に決めるための変数です。

この effort は、Claude が 1 回の返答にどれだけ手間をかけるかを決める設定で、API でも Claude Code でも使われています。

段階の意味と既定値、thinking との違い、Claude Code での切り替え方が分かると、「なぜ今日は返事が速いのか」「なぜ費用が増えたのか」にも説明がつきます。

effort とは何か

effort は、Claude が返答に使うトークンの量を、1 つのモデルのまま増やしたり減らしたりする設定です。

Anthropic の公式ドキュメントは、丁寧さとトークンの節約のどちらを取るかを 1 つの値で選べるもの、と説明しています。

Effort

効くのは考える部分だけではありません。

  • 本文の説明
  • ツールの呼び出しと、その引数
  • thinking(有効なとき)

返答のトークンすべてに効くので、thinking を使わない場合でも effort は意味を持ちます。

もう 1 つ大事なのは、effort が厳密な上限ではないことです。

ドキュメントには、effort は「振る舞いの合図」であってトークンの予算ではない、と書かれています。

低い段階でも、難しい問題なら Claude は考えます。

同じ問題を、高い段階のときより少なく考える、というのが低い effort の意味です。

5 つの段階と既定値

段階は low・medium・high・xhigh・max の 5 つで、API の Messages API では output_config.effort に名前を入れます。

段階向いている使い方(公式の説明の要約)
low速さと費用を優先する単純な作業。サブエージェントも例に挙がっている
medium速さ・費用・性能のバランスを取るエージェントの作業
high複雑な推論・難しいコーディング・エージェントの作業
xhigh30 分を超える長いエージェントやコーディングの作業
max費用を気にせず、いちばん深く考えさせたい作業

指定しないときは、モデルごとの既定値が使われます。

API の既定は多くのモデルで high ですが、Opus 5.5 と Haiku 5.5 は mediumです。

既定値と同じ値を明示しても、指定しないときと動きは変わりません。

Claude Code の既定は少し違い、Opus 5.5・Sonnet 5.5・Haiku 5.5 が medium、Opus 4.7 が xhigh、それ以外は high です。

Sonnet 5.5 は API では high が既定と書かれているので、API と Claude Code で同じモデルを使っても、何も指定しなければ段階がずれます。

また、すべてのモデルが 5 段階を持つわけではありません。

たとえば Opus 4.6 と Sonnet 4.6 には xhigh が無く、Claude Code で xhigh を選ぶと high として動きます。

段階の物差しはモデルごとに調整されていて、同じ「medium」でもモデルが違えば中身は同じではありません。

thinking との違い

effort とよく混ざるのが thinking の設定です。

公式の整理では、thinking は「答える前に thinking ブロックで考えるかどうか」、effort は「返答全体にどれだけ手間をかけるか」を決めます。

adaptive thinking(考えるかどうかとその量をモデルが選ぶ方式)では、どのくらい頻繁に、どれだけ深く考えるかも effort で変わります。

adaptive は thinking のモードの名前で、effort の値ではありません。

Opus 5.5 では adaptive thinking が常に有効で、切ることができません。

thinking: {"type": "disabled"} を送ると、どの段階でも 400 エラーになります。

そのため Opus 5.5 では、考える量と費用を決める主な手段は effortです。

ツールを使う場面でも違いが出ます。

ドキュメントによると、低い段階では呼び出しをまとめて回数を減らし、前置きなしで動き、終わったあとの報告も短くなります。

高い段階では呼び出しが増え、動く前に計画を説明し、変更の要約やコードのコメントも詳しくなる傾向があります。

thinking の仕組みそのものは、推論モデルの記事で扱いました。

推論モデルとは?答える前に考えるAIの仕組みと使いどころ

API で指定する

API では、リクエストの output_config に段階の名前を入れます。

# 公式ドキュメントの例から抜粋(ヘッダーの一部を省略)
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "..."}],
    "output_config": {"effort": "medium"}
  }'

ベータのヘッダーは要らず、対応するモデルならそのまま使えます。

気をつけたいのは、会話の途中で段階を変えるときです。

トップレベルの output_config.effort を次のリクエストで変えると、プロンプトキャッシュが最初からになります。

長い会話でキャッシュに頼っているなら、段階は最初に決めて変えないのが基本です。

Opus 5.5・Sonnet 5.5・Haiku 5.5 などでは、ベータのヘッダー mid-conversation-output-config-2026-07-01 を付けると、メッセージ単位で段階を変えられます。

こちらは中身が空の system メッセージに段階だけを載せる方法で、それより前の部分が変わらないためキャッシュが残ります。

Claude Code で切り替える

Claude Code では、effort をいくつかの場所から指定できます。

  • /effort(引数なしでスライダー、/effort high のように直接指定も可)
  • /model のスライダー(左右の矢印キー)
  • 起動時の --effort
  • 環境変数 CLAUDE_CODE_EFFORT_LEVEL
  • 設定ファイルの modelSettings(モデルごと)や effortLevel
  • スキルやサブエージェントの定義(frontmatter)の effort

いくつも指定したときは、Claude Code のドキュメントに書かれた順で、先に当てはまったものが使われます。

Model configuration - Claude Code Docs
  1. 環境変数 CLAUDE_CODE_EFFORT_LEVEL
  2. セッションの中で選んだ段階(/effort や /model)
  3. 起動時の --effort
  4. 設定ファイルに保存した段階
  5. モデルの既定値

環境変数がいちばん強いので、/effort で変えたのに変わらないときは、まずこの変数が設定されていないかを見てください。

max は特別扱いで、環境変数で指定しない限りそのセッションだけに効き、保存されません。

いまの段階は /effort status で確かめられます。

Bash ツールの中では、環境変数 CLAUDE_EFFORT にそのときの段階が入ります。

ultrathink は 1 回だけ段階を上げる

プロンプトのどこかに ultrathink と書くと、セッションの設定を変えずに、その 1 回だけ深く考えさせられます。

2.1.311 以降は、ターミナルで入力した ultrathink が、対応するモデルではその回を xhigh に上げます。

上げられるときは、入力した文字が虹色に光ります。

2.1.316 では、VS Code でも同じく xhigh で動くようになりました。

「think」「think hard」などはキーワードとして扱われず、ふつうの文として渡されます。

同じ版で、ultrathink を無効にする CLAUDE_CODE_DISABLE_ULTRATHINK も加わっています。

サブエージェントの effort

サブエージェントの段階は、これまで定義ファイルの effort か、呼び出しごとの effort で決められました。

どちらも無いときは、親のセッションの段階を引き継いでいました。

Claude Code の CHANGELOG によると、2.1.316 の CLAUDE_CODE_SUBAGENT_EFFORT は、ほかに指定が無いときにサブエージェントが使う段階を決めます。

claude-code/CHANGELOG.md at main · anthropics/claude-code

API のドキュメントは low の使い道としてサブエージェントを挙げているので、調べ物を任せる子だけ段階を下げる、という調整がしやすくなりました。

なお CLAUDE_CODE_EFFORT_LEVEL を設定していると、サブエージェントの定義の effort より環境変数が優先されます。

サブエージェントがトークンをどこで使うかは、別の記事で数えています。

サブエージェントのトークン、4割はCLAUDE.mdだった

選び方と落とし穴

公式ドキュメントのモデルごとの勧めには、共通する考え方があります。

自分の作業で品質を確かめながら段階を上げ下げし、確かめないまま別の段階に固定しない、ということです。

effort を動かしても足りないときに、4 つのモデルをどの順で上げ下げするかは、モデルの選び方の記事にまとめました。

Claudeモデルの選び方|4モデルの使い分けとeffort

段階の選び方で、はまりやすい点を挙げます。

  • 古いモデルの段階を持ち越さない: Opus 5.5 の medium は、Anthropic の試験で Opus 5 の high と同等以上だったとされます。乗り換えたら medium から試すよう勧められています。
  • max は様子を見てから: Claude Code のドキュメントは、max は伸びが小さくなりやすく、考えすぎにもなりやすいと書いています。
  • 高い段階では max_tokens を大きく: max_tokens は thinking と本文を合わせた上限なので、xhigh や max では足りなくなりがちです。
  • 返答の長さは effort で決まらないことがある: Opus 5 では、effort を下げても見える返答が短くなるとは限らず、長さはプロンプトで指示するよう書かれています。

Claude Code のドキュメントによると、Opus 5.5 と Fable 5.1 の試験では、高い段階ほど境目のケースを多く試し、答える前の確認も増えました。

低い段階では最初のたたき台が早く返るので、1 回ごとに結果を見て指示を足す作業に向いています。

段階を上げるか下げるかは、「自分がどれだけ途中で口を出すか」で考えると決めやすくなります。

最後に

effort は、Claude が返答全体にかける手間を low から max の 5 段階で決める設定で、考える量だけでなくツールの呼び出し方や説明の長さにも効きます。

既定値はモデルと製品で違い、Opus 5.5 は API でも Claude Code でも medium です。

Claude Code では環境変数がいちばん強く、ultrathink は 1 回だけ、CLAUDE_CODE_SUBAGENT_EFFORT はサブエージェントだけを動かします。

まず既定値で使い、自分の作業で確かめながら 1 段ずつ動かすのが、費用と品質の両方を外さない近道です。

以上です。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA