メインコンテンツまでスキップ

Effort チューニング:5 レベル、モデル別デフォルト、キャッシュの罠

中級

2026 年 7 月 22 日、Anthropic は Claude Managed Agents のモデル設定に effort を展開し、Messages API がひっそりと 5 レベルに成長したコントロールのループを閉じました。2026 年初頭のブログ投稿から messages.create のトップレベルに effort="high" をコピペしているなら、リクエストは有効に見えますが Claude はあなたが思うフィールドを尊重していないかもしれません — パラメータは今 output_config 内にあり、API はモデルカードにドキュメント化されたレベルのみを強制します。

これは実践的なチューニングガイドです。effort がリクエストのどこに実際に入るか、5 レベルが実際に何をするか(thinking の深さだけでなくツール呼び出し回数を変える)、驚くほどのモデル別デフォルト、そして支出を静かに膨らませる 1 つの落とし穴 — 会話中に effort を変更するとプロンプトキャッシュが無効化されること。

What you'll learn
  • effort フィールドを正しく配置する — Messages API では output_config 内、Managed Agents では model オブジェクト内、Claude Code では /effort または CLAUDE_CODE_EFFORT_LEVEL
  • モデルごとに開始レベルを選ぶ — API のデフォルトは high だが推奨開始 effort はモデルによって異なる(Sonnet 5 high、Sonnet 4.6 medium、Opus 4.7/4.8 xhigh、Fable 5 high)
  • effort はすべてのトークンに影響することを理解する — テキスト、ツール呼び出し、(アクティブなとき)thinking — なので effort を下げると単なる冗長さではなくツール呼び出し回数を減らす
  • キャッシュの罠を避ける — 1 つの会話内で effort を変えるとプロンプトキャッシュが無効化され、静かに請求が倍になる可能性がある
  • Claude Code の effort 表面を知る — /effort、ultrathink(1 ターン)、ultracode(xhigh + 常時マルチエージェント許可)、CLAUDE_CODE_EFFORT_LEVEL 環境オーバーライド

5 レベル(そして「ultracode」の位置)​

2026 年 7 月 22 日時点の effort スケールは、API が受け付ける 5 つの値を持ちます:

レベル何をするかいつ使うか
low最も効率的。ある程度の能力低下を伴う顕著なトークン節約。ツール呼び出しが少なく、簡潔な確認、前置きなし。シンプルな分類、大量ワークロード、チャット、レイテンシに敏感な UX、スコープされた作業を行うサブエージェント
mediumバランス型。high に対して適度なトークン節約。速度 + コスト + 品質のバランスが必要なエージェントタスク。high からのコスト意識的なステップダウン
high高能力。パラメータを省略するのと等価。複雑な推論、難しいコーディング、速度より品質が重要なエージェントタスク
xhigh長時間作業のための拡張能力。high より意味のあるほどトークン使用量が高いと予期される。長時間(30 分以上)のエージェント・コーディングタスク、数百万トークンの予算、深い複数ファイルリファクタ
max絶対的な最大能力、トークン支出の制約なし。真のフロンティア問題のみ。構造化出力タスクでは考えすぎる可能性あり。

max は effort をサポートするモデル全体で普遍的です。xhigh はより新しく、Fable 5、Mythos 5、Opus 4.8、Opus 4.7、Sonnet 5 でのみサポートされます。古い effort 対応モデル(Sonnet 4.6、Opus 4.6、Opus 4.5)は max を理解しますが xhigh は理解しません。

Pro tip
  • effort='high' を設定するのはパラメータを省略するのと全く同じ挙動を生みます — キャッシュされた会話で「明示的に」設定しないでください。あるリクエストでフィールドを書いて他で書かないとキャッシュが無効化されるためです。
  • 'ultracode' は 6 番目のレベルではありません。xhigh + Claude Code がマルチエージェントワークフローを起動する常時許可の組み合わせで、会話途中のシステムメッセージを介して付与されます。API は 5 つの値を受け付けます。

多くのブログ投稿が間違えるフィールド構造​

2026 年初頭の effort パラメータの書き方はトップレベルフィールドを示していました:

# WRONG on current models — silently ignored or 400
client.messages.create(
    model="claude-opus-4-8",
    effort="medium",
    ...
)

現在の API は effort を output_config オブジェクト内に配置し、messages/model の兄弟として渡します:

Messages API での正しい effort 配置

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
  model="claude-opus-4-8",
  max_tokens=4096,
  output_config={"effort": "medium"},
  messages=[{
      "role": "user",
      "content": "Analyse the trade-offs between microservices and monoliths."
  }],
)

print(response.content[0].text)

Claude Managed Agents(2026 年 7 月 22 日の変更)では、effort はエージェントの model オブジェクト内に作成時に入ります。セッションはそれを設定しません — エージェントのバージョンが設定します。

Managed Agents での正しい effort 配置(POST /v1/agents)

# Effort travels with the versioned agent config,
# not the per-run session. Every session pinned to
# this agent version runs at xhigh.

POST https://api.anthropic.com/v1/agents
{
"name": "code-reviewer",
"model": {
  "id": "claude-opus-4-8",
  "effort": "xhigh"
},
"system_prompt": "You review pull requests for security issues.",
"tools": [...],
"mcp_servers": [...]
}

Effort は thinking コントロールではない​

これが 2 つ目の大きな誤解です。Effort は thinking が有効かどうかに関わらず 動作し、レスポンスの thinking 以外の部分に Claude が費やすトークンを変えます:

  • ツール呼び出し。 effort が低い → ツール呼び出しが少ない。Claude は操作を単一の呼び出しにまとめ、オプションの探索をスキップし、前置きなしにアクションに進みます。
  • テキスト長。 effort が低い → 出力が引き締まる。ツール呼び出し後の詳細なサマリーではなく簡潔な確認。コードコメントが少なく。
  • Thinking の深さ(thinking がオンのとき)。effort が低い → 簡単なプロンプトでは thinking を完全にスキップ。真に難しい問題では引き続き考える、少なく。

最後の点が重要:low effort でも証明問題では Claude はまだ考えます、タスクがそれを要求するので。Effort は 挙動シグナル であり、厳格なトークン予算ではありません。ハードキャップを期待しないでください。

thinking パラメータと effort パラメータは異なる質問に答えます。thinking は Claude が thinking ブロックを生成するかどうかを決めます。effort はレスポンス全体にどれだけの作業が入るかを決めます — adaptive thinking がオンのときに Claude がどれだけ頻繁にどれだけ深く考えるかを含めて。effort="adaptive" を渡すのは一般的な間違いです。adaptive は thinking モード であり、effort レベルではありません。

Pro tip

Opus 4.5 — effort をサポートする唯一の extended-thinking-only モデル — では effort と budget_tokens を一緒に設定します。タスク用に effort レベルを選び、次に推論の深さ用に thinking トークン予算をサイジングしてください。他のすべての effort 対応モデルは adaptive thinking を使用し budget_tokens を取りません。

チームを驚かせるモデル別開始点​

API のデフォルトはパラメータをサポートするすべてのモデルで high です。しかし Anthropic の 推奨開始 effort はモデルによって異なり、そのミスマッチが過剰・過少支出の元です。

Guided walkthrough1 of 6
  1. Sonnet 5 は API と Claude Code の両方で high をデフォルトとし、推奨は一致します。最も難しいコーディング・エージェントタスクにのみ xhigh にステップアップしてください。コスト削減の動きとして medium にステップダウン — Sonnet 5 の medium は Sonnet 4.6 の high に匹敵します。チャットや非コーディング、レイテンシ敏感なワークロードには low を使ってください。

キャッシュの罠 — 静かに請求を倍にするもの​

プロンプトキャッシングは標準入力価格の約 10% でキャッシュ読み取りを提供します。同じ会話内でリクエスト間で effort を変えると、モデルを切り替えるのと全く同じように キャッシュが無効化 されます。長いコンテキストでは、$0.03 のキャッシュ読み取りと履歴全体の $0.30 のフルプライス再読み取りの差です — すべてのフォローアップターンで。

Pro tip
  • effort は ワークロード間で変えて、キャッシュされた会話内では変えないでください。会話開始時にレベルを選び、/clear するまで一定に保ってください。
  • Claude Code では、セッション途中の /effort はモデル切り替えと同等です — 次のターンで大きなキャッシュミスを予期してください。
  • 1 ターンだけ深さをエスカレートする必要がある場合、/effort xhigh ではなく Claude Code の 'ultrathink'(1 ターンの深い推論バンプ)を使ってください — セッション設定を変えないので回避できます。
  • 残りのセッションでエスカレートしなければならない場合、早めにやってください。ターン 3 での切り替えは安い。ターン 30 での切り替えはフルプライスで 30 ターンのコンテキストを再読み取ります。

その帰結:キャッシュされたリクエストの一部で effort="high" を明示的に設定し、他で省略するのも同じ方法でキャッシュを無効化します — 両者は 挙動的に 等価だが テキスト的に 異なるからです。1 つの規約を選んで(常に設定するか、常に省略するか)、それを保ってください。

Claude Code — CLI 表面​

Claude Code は effort をインタラクティブコマンド、起動フラグ、環境変数として公開します(逆順で最も優先度の高いものが勝つ):

# In-session (interactive slider, or direct)
/effort
/effort xhigh
/effort auto           # reset to model default

# At launch
claude --effort low

# Environment (overrides everything else)
CLAUDE_CODE_EFFORT_LEVEL=high claude

関連する 2 つのコマンドは effort レベルではないが隣接して振る舞うので知る価値があります:

  • ultrathink — セッションの effort を 変えない 1 ターンの深い推論バンプ。次のターンにより深く考えさせたいが、その後のすべてのターンでキャッシュを無効化したくない場合に使ってください。
  • ultracode — セッション全体で xhigh を設定し、加えて Claude Code にマルチエージェントワークフローを起動する常時許可を(会話途中のシステムメッセージを介して)付与します。API には ultracode 値はありません — CLI の便宜で、xhigh にオーケストレーション許可を組み合わせたものです。

覚えておくべき永続性ルール:low、medium、high、xhigh は一度設定すると Claude Code セッション間で永続化されます。max は現在のセッションのみに適用されます — 次回再適用しなければなりません。

チューニングウォークスルー — 1 つのプロンプト、3 つの effort​

直感をキャリブレートするために、同じ プロンプトを 3 つのレベルで実行して出力の形を比較してください:

チューニングキャリブレーションプロンプト(low、high、xhigh で実行)

Task: Review this pull request for security issues.

<pr_diff>
[paste a real diff — 300+ lines, multi-file, at least one auth-touching change]
</pr_diff>

Report: severity-tagged findings + a one-line fix per finding.
Do not restate what the diff does.

おおよそ予期してください:

  • low — 明らかな高深刻度の問題(SQL 文字列連結、ヘッダー内の未チェックユーザー入力)を捕まえる。微妙なロジックバグは見逃す。ツールが利用可能なら 1〜2 ツール呼び出し。短い出力。速い。
  • high — 完全な分析。微妙なものを含むほとんどの脆弱性を捕まえる。関連ファイルを読むための複数のターゲットされたツール呼び出し。構造化された所見。ほとんどのチームがここで止まる。
  • xhigh — 網羅的。新しい攻撃ベクトルと多層防御を考慮。low/high が触れなかった隣接ファイルを読む。はるかに多くのツール呼び出し。意味のあるほど高いトークン使用量。

評価が high と xhigh が同じ所見をコードベースで生成することを示す場合、high で出荷してください。Xhigh の価値は、タスクが繰り返しのツール呼び出しと詳細な探索から利益を得るときに具体的に現れます — それは Anthropic が推奨するときです。

Sonnet 5 はキャリブレーションをシフト — レベルを盲目的に移植しない​

Sonnet 4.6 を high で走らせていて Sonnet 5 に移行した場合、同じレベルを保つと Sonnet 5 は Sonnet 4.6 が max で費やしたものに近く支出します — Sonnet 5 の effort スケールは シフト しています。Anthropic 自身のガイダンス:Sonnet 5 の medium ≈ Sonnet 4.6 の high。effort を調整せずにトラフィックを再生した場合、リクエスト単価のスイングは確認する価値があります。完全な移行ストーリーは Sonnet 5 フィールドガイド を参照してください。

確定させる​

Enter キーまたはスペースキーでカードを裏返します。左右の矢印キーでカードを移動できます。用語を表示しました。
1 / 8

確認しよう

0/6
  1. Messages API で有効な effort 値でないのはどれ?
  2. キャッシュされた 20 ターンの会話を走らせています。ターン 21 で effort を high から xhigh に切り替えると何が起こる?
  3. Claude Code にいて、セッションの effort 設定に触れずに次のターンだけをより強く推論させたい。最良の動きは?
  4. Opus 4.8 で effort='xhigh' のとき、長い thinking の後にレスポンスが stop_reason='max_tokens' で切り詰まり続けます。最も可能性の高い修正は?
  5. Claude Managed Agents エージェントを作成するとき(2026 年 7 月の更新)effort はどこに入るか?
  6. Sonnet 5 の 'medium' を Sonnet 4.6 の 'high' に最も近く振る舞わせる変化は?

ソースとさらに読む​