Claude の adaptive thinking と effort の使い方 — budget_tokens からの移行と 5 段階の選び方

Claude API で「どれだけ考えさせるか」の制御は、2026 年に根本から変わりました。固定予算（budget_tokens）は廃止され、モデルが課題に応じて考える量を決める adaptive thinking と、全体の深さを 5 段階で指定する effort に置き換わっています。

旧: budget_tokens → 新: adaptive + effort

# 旧（4.7 以降と Sonnet 5 では 400）
thinking={"type": "enabled", "budget_tokens": 8000}

# 新
thinking={"type": "adaptive"},
output_config={"effort": "high"},   # low | medium | high | xhigh | max

budget_tokens は「どれだけ考えるか」、effort は「どれだけ考え、どれだけ行動するか」を決めるので、1 対 1 の対応はありません。effort は output_config の中に書きます。トップレベルではありません。

モデルごとの既定値

ここが移行の落とし穴です。

モデル	thinking 省略時	disabled
Opus 4.7 / 4.8、Sonnet 4.6	思考なし	可
Claude Opus 5	adaptive（思考する）	effort high 以下でのみ可
Claude Sonnet 5	adaptive	可
Claude Opus 5.5（9/22〜）	常時 adaptive	400（thinking を書かない。既定 effort は medium）
Claude Sonnet 5.5（9/28〜）	adaptive	400 → {type: "between_tools"}（high 以下、他のフィールド不可）
Claude Haiku 5.5（10/7〜）	adaptive（Haiku 初。既定 effort は medium）	effort high 以下でのみ可
Claude Fable 5.1	常時 adaptive	400（thinking を書かない）

4.8 で thinking を書かずに動いていたコードは、Opus 5 に変えた瞬間に思考を始めます。エラーは出ませんが、max_tokens は思考＋本文の合計上限なので、max_tokens=1024 のような経路では本文が途中で切れて stop_reason: "max_tokens" になります。思考を活かすなら max_tokens を 16,000 以上（エージェントは 64,000）に、旧挙動を保つなら disabled を明示します。

effort の 5 段階

レベル	用途
max	知能が最優先でトークン制約が無い。簡単な課題では考えすぎる
xhigh	コーディング・エージェントの最良設定。Claude Code の既定
high	既定。知能が要る作業の最低ライン
medium	費用を抑えたい作業。Sonnet 5 の medium は Sonnet 4.6 の high 相当
low	短く範囲の決まった作業、遅延に敏感な経路

Opus 5 は low / medium が異常に強いのが特徴です。公式の計測では、研究・知識作業で low は精度 1〜3 ポイント減で費用 1/2〜1/3、medium は既定と同精度で費用 70〜85% でした。前のモデルの effort 設定を持ち越さず、high から下へ掃いて測り直すのが基本です。

xhigh / max では max_tokens を 64K 以上にします。思考と行動に場所が要るからです。

Opus 5.5 の既定は medium です。Opus 5 から effort を省略したまま移すと 1 段低い effort で走るので、必ず明示して medium を起点に掃き直します。公式の計測では Opus 5.5 の medium は Opus 5 の high と同等以上でした。Sonnet 5.5 は各レベルが再較正されているので、Sonnet 5 の設定を持ち越さず、エージェント的なコーディングは medium、一般は high を起点にします。Haiku 5.5 は Haiku 系で初めて effort を持ち、budget_tokens からの持ち越しはありません。起点は medium、チャットや単純な大量処理は low、厳密な指示追従は high。xhigh / max は Sonnet 5.5 と比べてから。

思考をオフにする前に

2026 年 9 月以降のモデルでは disabled 自体が 400 です。Opus 5.5 と Fable 5.1 は思考を切れません（effort を下げる）。Sonnet 5.5 では thinking: {type: "between_tools"} が最低設定で、前置きの思考はせず、ツール呼び出しの間の短い思考だけ残ります。high 以下でだけ使え、display / budget_tokens / block_binding を併記すると 400、メッセージ単位の effort 変更とも併用できません。ツールのないリクエストで数ステップの計算が要るなら adaptive に戻します。

thinking: {type: "disabled"} は Opus 5 では effort high 以下でだけ使え、xhigh / max と組むと 400 です。さらに Opus 5 には、思考オフのときにだけ出る症状が 2 つあります。

1. ツール呼び出しを tool_use ブロックではなく本文テキストに書いてしまう。ターンは正常終了し、呼び出しは実行されない
2. <thinking> タグが本文に漏れる

公式ガイドの第一の処方は「思考をオンに戻して effort を下げる」です。それでもオフが必要なら、次の 1 文で両方を抑えられます。

"When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response."

「考えるな」という指示はタグ漏れを増やすので削除し、<thinking> タグを名指ししないのがコツです。

思考の本文は既定で空

4.7 以降と Sonnet 5 は thinking.display の既定が omitted で、thinking ブロックは返るが本文が空です。思考をユーザーに見せる製品では、ストリームが「長い沈黙のあと突然本文」に見えます。

thinking={"type": "adaptive", "display": "summarized"}

display は見え方だけを変え、思考と課金は同じです。Fable 5.1 では display: "updates"（ベータ）で、ツール呼び出しの間の進捗更新だけを受け取れます。

effort を測る

最適な effort は作業ごと・モデルごとに違います。固定した評価セットを effort ごとに流し、合格率と 1 件あたり費用を並べて決めます。設定ごとに全件を順に流し、1〜2 件の差は誤差として試行を重ねる、というのが公式の作法です。

評価セットを effort ごとに流すスクリプトを公開しています。

python claude5-migration-kit/effort_sweep.py --model claude-opus-5-5 --levels low,medium,high eval.jsonl

モデル別の移行手順と、キャッシュ・履歴・プロンプト再調整までを扱った本を Zenn で公開しています。

• Claude 5 世代 移行ガイド