思考のステアリング

Claudeの思考は適応的です。モデルは各リクエストを評価し、思考するかどうか、またどの程度思考するかを自ら判断します。あなたは意図を設定し、必要に応じてエフォートを指定するだけで、モデルは推論が役立つと判断した箇所に推論を割り当てます。

このため、思考は、些細なリクエストと複雑なリクエストが混在するワークロードや、ステップごとに適切な推論量が変化する長期的なエージェントワークフローに非常に適しています。

思考を有効にする方法、思考出力の読み方、およびClaude Fable 5とClaude Mythos 5における思考出力については、思考の概要を参照してください。このページでは、Claudeがいつ思考するかをどのように決定するか、その決定をどのようにステアリングするか、そしてそこから生じるキャッシング、コスト、料金の仕組みについて説明します。

Claudeがいつ思考するかを決定する仕組み

思考はモデルにとって任意です。各リクエストにおいて、Claudeは入力の複雑さを評価し、より深い推論によって回答が改善されるかどうかを判断します。単純な事実に関する質問には、思考ブロックをまったく含まない直接的な応答が返されることがあります。一方、複数ステップの数学問題や厄介なデバッグタスクでは、より深い推論がトリガーされます。

この決定はリクエストごとに行われます。同じ会話の中に、思考を伴うターンと伴わないターンが含まれることがあり、Claudeが思考しないことを選択したターンには思考ブロックが含まれません。すべてのアシスタントターンが思考ブロックで始まることを前提としたアプリケーションロジックを構築しないでください。

この決定に対する主要な制御手段はeffort（エフォート）パラメータです。これは、Claudeがどの程度積極的に思考すべきか、またどの程度深く思考すべきかについてのソフトなガイダンスとして機能します。各レベルの動作については、このページのエフォートレベルを参照してください。

Claudeに思考の頻度を減らしてほしい場合は、プロンプトベースのステアリングに手を伸ばす前に、エフォートレベルを下げてください。

思考はツール使用とも自動的にインターリーブされます。Claudeはツール呼び出しの間に思考し、次に何をするかを決定する前に各ツール結果について考察できます（インターリーブ思考）。これにはベータヘッダーや追加の設定は必要ありません。

思考の設定とエフォートパラメータがどのように相互作用するかの全体像については、思考とエフォートを参照してください。

Claudeが思考する頻度のステアリング

Claudeが特定のターンで思考するかどうかは、プロンプトで制御可能です。エフォートは全体的な姿勢を設定しますが、システムプロンプトでグローバルに、またはユーザーターンからメッセージごとに、自然言語のガイダンスで決定を直接形作ることもできます。

2つのレバーを次の順序で組み合わせて使用してください。

1. ワークロードにおける品質とレイテンシのデフォルトのバランスに合ったエフォートレベルを設定します。
2. そのレベルでもClaudeのトリガー動作がニーズに合わない場合にのみ、プロンプトによるガイダンスを追加します。

思考に関するより広範なプロンプティングのガイダンスについては、思考およびインターリーブ思考の機能を活用するを参照してください。

エフォートレベル

エフォートは思考に対する主要なステアリングレバーです。各レベルは、Claudeがどのくらいの頻度で、どのくらい深く思考するかについて異なるデフォルトを設定します。

この表は、各レベルが思考の動作をどのように変化させるかを説明しています。モデルごとの推奨事項を含め、特定のワークロードに対してどのレベルを選択すべきかのガイダンスについては、エフォートページのエフォートパラメータを調整すべきタイミングを参照してください。

エフォートはthinkingオブジェクト内ではなく、output_config.effortで設定します。言語ごとの完全な例については、エフォートを参照してください。

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

レベルの利用可否はモデルによって異なります。各モデルがどのレベルをサポートしているかについては、エフォートページのエフォート利用可否の表が正式な情報源です。

システムプロンプトによるガイダンス

システムプロンプトによるガイダンスは、会話内のすべてのリクエストに対してClaudeの思考のしきい値を変化させます。Claudeがワークロードに必要な以上に頻繁に思考している場合は、次のようなガイダンスをシステムプロンプトに追加してください。

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.

逆に思考を促したい場合は、次のようなフレーズを使用してください。

This task involves multistep reasoning. Think carefully before responding.

ステアリングの効果は、正確な言い回しに左右されることがあります。ある言い回しで望む動作が得られない場合は、より直接的な表現を試してください。

メッセージごとのステアリング

システムプロンプトとは独立して、ユーザーターンからメッセージごとに思考をステアリングすることもできます。ユーザーメッセージに"Please think hard before responding."を追加すると、Claudeはそのターンで思考するよう促されます。"Answer directly without deliberating."を追加すると、思考が抑制されます。

メッセージごとのステアリングは、会話内の一部のリクエストのみが拡張された推論を必要とする場合に便利です。たとえばエージェントハーネスでは、システムプロンプトに触れたり、ターン間でリクエストパラメータを変更したりすることなく、計画ステップでは思考を促すフレーズを、定型的な確認では抑制するフレーズを追加できます。

ワークロードでステアリングを検証する

プロンプトベースのステアリングはモデルの動作を変化させるため、他のプロンプト変更と同様に扱ってください。つまり、リリース前に測定してください。トラフィックの代表的なサンプルをガイダンスありとなしで実行し、思考がトリガーされる頻度（応答内の思考ブロックの有無）、出力トークン使用量、レイテンシ、そして重要なケースにおける回答品質を比較してください。

仕組み

Claudeが自身の思考を管理することから、3つの仕組みが生じます。ターンの検証、プロンプトキャッシング、そしてコストの上限設定方法です。

ターンの検証

アシスタントターンは思考ブロックで始まる必要はありません。（レガシーの手動思考バジェットを使用するモデルでは、思考が有効なリクエストの最後のアシスタントターンが思考ブロックで始まることが強制されます。手動モードにおけるターン構造を参照してください。）

マルチターンアプリケーションにとって、これは会話履歴をどのような形であってもそのまま渡せることを意味します。

• Claudeが思考しないことを選択したアシスタントターンは、そのままで有効な履歴です。
• 思考なしで始まった会話や、異なる思考設定を使用していた会話を、履歴を書き換えることなく再開できます。
• 複数のソースから組み立てられた履歴は、検証を通過するために各アシスタントターンの先頭に思考ブロックを再挿入する必要はありません。

この緩和は検証に関するものであり、何を送信すべきかに関するものではありません。思考ブロックがある場合は、変更せずにそのまま渡してください。特にツール使用中は、思考ブロックがClaudeのツール呼び出しの背後にある推論を保持しているため重要です。完全なルールについては、思考の概要を参照してください。

プロンプトキャッシング

同じ思考設定とエフォートレベルを維持する連続したリクエストでは、「prompt caching」（プロンプトキャッシング）が保持されます。完全なルールについては、思考とプロンプトキャッシングを参照してください。解決されたエフォート値はプロンプトにレンダリングされるため、リクエスト間でこれを変更するとキャッシュブレークポイントが無効になります。これは、レガシーのbudget_tokensパラメータを使用するモデルでそれを変更した場合と同様です。effortをモデルのデフォルトに明示的に設定することは、省略することと同等であり、キャッシュを壊しません。

実用上の結論として、会話ごとに思考設定とエフォートレベルを選択し、それを維持してください。一部のターンでより多くまたはより少ない思考が必要な場合は、メッセージごとのプロンプティングでステアリングしてください。最新のユーザーメッセージに追加されたガイダンスは、それ以前のキャッシュブレークポイントをそのまま維持しますが、設定やエフォートの変更はそうではありません。

次の例は、自分で実行できるマルチターンスクリプトを使って、この無効化を示しています。

import requests

client = Anthropic()


def fetch_article_content(url):
    text = requests.get(url).text
    lines = (line.strip() for line in text.splitlines())
    return "\n".join(line for line in lines if line)


# 記事のコンテンツを取得
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# キャッシングに十分な量のテキストのみを使用（最初の数章）
LARGE_TEXT = book_content[:10000]

# システムプロンプトなし - 代わりにメッセージ内でキャッシング
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Analyze the tone of this passage."},
        ],
    }
]

# 1回目のリクエスト - キャッシュを確立
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})

# 2回目のリクエスト - 同じ設定（キャッシュヒットを想定）
print("\nSecond request - same configuration (cache hit expected)")
response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({"role": "assistant", "content": response2.content})
MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})

# 3回目のリクエスト - 異なるeffortレベル（キャッシュミスを想定）
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=MESSAGES,
)

print(f"Third response usage: {response3.usage}")

First request - establishing cache
First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 }

Second request - same configuration (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 }

Third request - different effort level (cache miss expected)
Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 }

コスト制御

思考トークンのバジェットは設定しません。2つの制御手段がコストの上限を定めます。

• max_tokensは、思考と応答テキストを合わせた、リクエストの総出力に対するハードキャップです。Claudeがこれを超えて生成することはありません。ツール使用ループでは、ターン内の各リクエストがそれぞれ独自のmax_tokensを持つため、ターン全体の消費量の上限にはなりません。
• effortは、その出力のうちClaudeがどれだけを思考に割り当てるかについてのソフトなガイダンスです。動作を形作りますが、トークン数を保証するものではありません。

思考はmax_tokensにカウントされるため、推論と回答の両方に余裕を残せるよう十分に高く設定してください。思考なしの応答に合わせてサイズ設定されたmax_tokensは、Claudeが難しいリクエストで思考を始めると、小さすぎることがよくあります。

high以上のエフォートでは、Claudeは広範に思考する可能性があり、バジェットを使い切る可能性が高くなります。応答にstop_reason: "max_tokens"が表示される場合、2つの対処法があります。

• max_tokensを引き上げて、思考と回答のためにモデルにより多くの余裕を与えます。
• エフォートレベルを下げて、Claudeの思考を減らし、バジェットのより多くを応答テキストに残します。

どちらが正しいかは、切り捨てられた応答が推論を必要としていたかどうかによります。それらのリクエストの品質が重要であればキャップを引き上げ、過剰に思考していたのであればエフォートを下げてください。

料金

思考では、以下に対して料金が発生します。

• Claudeが思考中に使用するトークン（出力トークンとして課金）
• 保持のデフォルトに従ってコンテキストに残る、以前のアシスタントターンの思考ブロック。keep-allモデルではデフォルトですべてのターン、それ以外では最後のターンのみ（入力トークンとして課金）
• 標準のテキスト出力トークン

課金対象はdisplay設定に関係なく同じです。変わるのは表示される内容だけです。

内部推論に費やされた課金対象の出力トークン数を確認するには、応答内のusage.output_tokens_details.thinking_tokensを読み取ってください。この値は、モデルが生成した生の推論（本文で返される要約テキストではありません）を反映しており、常にoutput_tokens以下です。これをoutput_tokensから差し引くことで、出力の非推論部分を概算できます。ストリーミング時には、この内訳は最後のmessage_deltaイベントにのみ表示されます。

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

output_tokensは引き続き、課金に使用される包括的で正式な合計値です。output_tokens_detailsは、オブザーバビリティのための読み取り専用の内訳です。基本料金、キャッシュ書き込み、キャッシュヒット、出力トークンを含む完全な料金情報については、料金を参照してください。

次のステップ