ai-docs

Steering thinking

Properties1
tagsthinking, effort, costs, prompt-caching, api

10 min read

一行要約

thinking にトークン予算は設定しない。 費用を縛るのは max_tokens（厳密な上限）と effort（ソフトな指針）の2つだけ。そして effort を変えるとプロンプトキャッシュが壊れることが、実測ログ付きで示されている。

要点

effort レベルごとの thinking の振る舞い

effortthinking の振る舞い
max常に思考する。深さに制約なし
xhigh常に深く思考し、探索を拡張する
high（既定）ほぼ常に思考する
medium適度に思考する。単純なクエリでは飛ばすことがある
low思考を最小化する。速度が最重要な単純タスクでは飛ばす

The decision happens per request. The same conversation can contain turns with and without thinking, and a turn where Claude chose not to think contains no thinking block. Don’t build application logic that assumes every assistant turn starts with one. 判断はリクエストごとに行われる。同じ会話の中に thinking のあるターンとないターンが混在しうるし、Claude が考えないことを選んだターンには thinking ブロックが存在しない。すべての assistant ターンが thinking ブロックで始まると仮定したアプリケーションロジックを組むな。

制御の順序

  1. ワークロードの既定バランスに合う effort レベルを設定する
  2. そのレベルでもまだ合わないときにだけ、プロンプトによる誘導を足す

If you want Claude to think less often, lower the effort level before reaching for prompt-based steering. Claude が考える頻度を下げたいなら、プロンプトによる誘導に手を伸ばす前に effort レベルを下げよ。

誘導は2階層:

  • system prompt guidance — 会話中の全リクエストで閾値をずらす
  • per-message steering — user ターンから、そのターンだけ誘導する

Steering effectiveness can be sensitive to exact wording. If one phrasing doesn’t produce the behavior you want, try a more direct variant. **誘導の効き方は、言い回しの細部に左右されうる。**ある表現で望む挙動にならないなら、より直接的な言い方を試せ。

per-message steering の利点（キャッシュとの関係で重要）:

An agent harness can append the encouraging phrase on planning steps and the suppressing phrase on routine confirmations, without touching the system prompt or changing any request parameters between turns. エージェントの harness は、計画の段階では思考を促す語句を、定型的な確認では思考を抑える語句を追記できる。system prompt に触れることも、ターン間でリクエストのパラメータを変えることもなくである。

Prompt-based steering changes model behavior, so treat it like any other prompt change: measure before you ship. プロンプトによる誘導はモデルの挙動を変えるので、他のプロンプト変更と同じように扱え。出す前に測れ。

turn validation の緩和

Assistant turns don’t need to start with a thinking block. assistant のターンは thinking ブロックで始まる必要はない。

したがって:

  • Claude が思考しなかった assistant ターンは、そのまま有効な履歴
  • 異なる thinking 設定で始まった会話も、履歴を書き換えずに再開できる
  • 複数の出所から組み立てた履歴に、thinking ブロックを挿し直す必要はない

ただしこれは検証の話であって、送るべきものの話ではない。 thinking ブロックがあるなら、特にツール使用中は、そのまま返す。

prompt caching（実測付き）

The resolved effort value is rendered into the prompt, so changing it between requests invalidates cache breakpoints. Setting effort explicitly to the model’s default is equivalent to omitting it and does not break the cache. 解決後の effort 値はプロンプトにレンダリングされるため、リクエスト間でこれを変えるとキャッシュの breakpoint が無効になる。effort にモデルの既定値を明示的に設定することは、省略した場合と等価であり、キャッシュを壊さない。

The practical consequence: pick a thinking configuration and an effort level per conversation and keep them. If some turns need more or less thinking, steer with per-message prompting: guidance appended to the newest user message leaves earlier cache breakpoints intact, where a configuration or effort change does not. 実務上の帰結はこうである。会話ごとに thinking の設定と effort レベルを決め、それを保て。ターンによって思考量を増減させたいなら、メッセージ単位のプロンプトで誘導せよ。最新の user メッセージへの追記はそれ以前のキャッシュ breakpoint を壊さないが、設定や effort の変更は壊す。

コスト制御

You don’t set a thinking token budget. Two controls bound cost: **thinking のトークン予算を自分で設定するのではない。**コストを縛るのは次の2つの制御である。

制御性質
max_tokensリクエストの総出力（thinking + 応答テキスト）の厳密な上限。 Claude はこれを超えて生成しない。ツール使用ループでは各リクエストが独自の max_tokens を持つので、ターン全体の支出は縛らない
effortその出力のうちどれだけを thinking に配分するかのソフトな指針。トークン数を保証しない

A max_tokens sized for a response with no thinking is often too small once Claude starts thinking on hard requests. thinking なしの応答に合わせた max_tokens は、難しい依頼で Claude が考え始めると小さすぎることが多い。

stop_reason: "max_tokens" が出たときの2つの対処:

  • max_tokens を上げる — その推論が必要だったなら
  • effort を下げる — 考えすぎだったなら

課金

課金対象は3つ — thinking のトークン（出力トークンとして）、context に残る過去ターンの thinking ブロック（入力トークンとして）、通常のテキスト出力。

What you’re billed for is the same regardless of the display setting; only what you see changes. 課金される内容は display の設定によらず同じである。変わるのは見えるものだけである。

display: "summarized"display: "omitted"
課金される出力トークンClaude が内部生成した完全な thinking同じ
見える出力トークン要約された thinking テキストゼロ（thinking フィールドが空）
要約の生成課金なし該当なし

The billed output token count does NOT match the visible token count in the response. 課金される出力トークン数は、応答内で見えるトークン数と一致しない。

内訳を見る方法: レスポンスの usage.output_tokens_details.thinking_tokens。これは生の推論を反映し（本文に返る要約テキストではない）、常に output_tokens 以下。ストリーミング時は最後の message_delta イベントにのみ現れる。

When thinking is active, a specialized system prompt is automatically included to support this feature. thinking が有効なときは、この機能を支えるための専用の system prompt が自動的に含まれる。

そのまま使える具体例

思考を減らす（system prompt）:

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multistep reasoning. When in doubt, respond directly.

思考を促す（system prompt）:

This task involves multistep reasoning. Think carefully before responding.

per-message steering（キャッシュを壊さずにターン単位で調整できる）:

Please think hard before responding.      ← 思考を促す
Answer directly without deliberating.     ← 思考を抑える

effort の指定場所（thinking オブジェクトの中ではない）:

{
  "model": "claude-opus-4-8",
  "max_tokens": 4096,
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

effort 変更がキャッシュを壊す実測:

First request - establishing cache
  cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15
 
Second request - same configuration (cache hit expected)
  cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062
 
Third request - different effort level (cache miss expected)
  cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706

thinking トークンの内訳を読む:

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

運用の指針:

会話ごとに thinking 設定と effort を決めて固定する（キャッシュのため）
ターン単位の調整が要るなら per-message steering で行う
stop_reason: "max_tokens" が出たら
  → その推論が必要だった  : max_tokens を上げる
  → 考えすぎだった        : effort を下げる

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク