Oikonです。外資IT企業でエンジニアをしています。
みなさんはClaude Codeを日々使っている時にultrathinkを使っていますか？
今ではultrathinkというワードは、Claude Codeユーザーなら誰でも知ってると思いますが、この記事ではもう少し深掘りしたいと思います。
個人的に以下の点が気になり調べました：
- 常に
ultrathinkにできる？ -
MAX_THINKING_TOKENSは完全にトークン固定？ - どれくらいまで思考トークン予算を割り振ることができる？
そこまで目新しい話はないと思いますが、𝕏でそれなりに反応があったので多少需要があると思い、記事にしています。
記事の要約
-
ultrathink(31999 tokens)は思考トークン予算を増やす - 環境変数
MAX_THINKING_TOKENSで上書き可能(1024 ~ 200000) - パフォーマンスの観点からOpus 4 (31999以下), Sonnet 4 (63999以下)推奨
- envに設定することで、Thinking mode時は常に
ultrathinkにできる
settings.json(settings.local.json)
{
"env": {
"MAX_THINKING_TOKENS": "31999"
}
}
注意点：
- MAX_THINKING_TOKENSを上げ過ぎると上手くモデルが動いてくれない、タイムアウトのリスクがある
- あくまでThinking modeの思考予算の変更であり、Thinking modeには別途
Thinkを明示して入る必要があるという理解
拡張思考(Extended Thinking)
Claude 4は推論モデルのため、タスクを実行する際に内部推論をします。この際に思考予算（Thinking Budget）が割り振られます。
思考予算を明示的に引き上げるために、Claude Codeでは内部的にキーワードマッチ処理をしています。
英語(English)の例：
- HIGHEST(31999 tokens):
ultrathink,think harder - MIDDLE(10000 tokens):
megathink,think hard - BASIC(4000 tokens):
think
英語以外にも7言語に対応しています。
この辺りの話は、すでに以下の記事でも詳細に語られているので割愛します。
MAX_THINKING_TOKENSの仕様
設定方法
Claude Codeの思考予算はキーワードマッチにより決定されますが、環境変数MAX_THINKING_TOKENSで上書きもできます。
export MAX_THINKING_TOKENS=31999
正しく設定されたかはClaude Codeの起動時にOverridesが出ることで確認できます。
環境変数はClaude Codeの設定ファイルsettings.jsonでも個別で設定できます。
settings.json(settings.local.json)
{
"env": {
"MAX_THINKING_TOKENS": "31999"
}
}
環境変数については、Anthropic公式ドキュメントに記載があります：
最小値・最大値
MAX_THINKING_TOKENSは1024以上, 200,000以下の値を受け付けます。
200,000 tokensはClaude 4のコンテキストウィンドウの上限から来るものだと思っています（間違っていたら教えてください）
設定時の注意点
Claude 4のOutput tokenの上限は公式ドキュメントを見ると以下のようになっています。
Max output:
- Claude Opus 4: 32000 tokens
- Claude Sonnet 4: 64000 tokens
そのためMAX_THINKING_TOKENSをあまり高く設定すると、デメリットが生じるケースがあるようです。
新着さん（@lfji）からもMAX_THINKING_TOKENSについて注意点をいただいたので、こちらに引用させていただきます。
MAX_THINKING_TOKENSの値についてですが、Opusは31999、Sonnetは63999を上限として、それ以下の値に設定することをお勧めします。これ以上に大きな値を指定すると、かえってデメリットが生じるようです。
- まず、各モデルが1回のAPIコールで出力できるトークン数（Max output）には上限があり、Opusは32000、Sonnetは64000トークンとなっています。
- Claude Codeは、
MAX_THINKING_TOKENSに設定した値に+1した数値を、APIのmax_tokensパラメータに自動で指定してリクエストを送信します。- このため、
MAX_THINKING_TOKENSに前述の上限値以上を設定すると、初回のAPI呼び出しがトークン数上限を超過してエラーとなります。- Claude Codeは内部で
max_tokensパラメータを自動修正してリトライを行ってくれますが、このリトライ処理が実行されると、リアルタイムで応答を逐次返すストリーミング機能（Server-Sent Events）が動作しなくなります。- その結果、モデルからの応答がすべて完了するまで待機する処理に切り替わるため、Claude Codeのタイムアウト値に引っかかる場合があります。
せっかくモデルに生成させた応答が無駄になってしまう可能性もあるため、初めからAPIエラーを回避できるよう、
MAX_THINKING_TOKENSは上記の上限値以下に設定するのが良さそうです。
追加調査
念の為MAX_THINKING_TOKENSの挙動を自分でも確認しようと思い、実際にClaude Codeのソースコードを解析させてみました。
調査手順は以下の通りです：
- ContainerでClaude CodeのDockerfileをbuild
- 展開されたソースコード内を走査
- 該当部分をClaudeに解析させる
展開にはappleのcontainerを使ってみています（使ってみたかったので）。
Containerについては、以下の記事を参考にしました。
コンテナをビルドして中に入ります。
container build -t claude-code .
container run -it claude-code zsh
node_modulesの場所を特定します。
> npm root -g
/usr/local/share/npm-global/lib/node_modules
node_modulesの中に@anthropic-ai/claude-codeがあるのでさらに中に入ります
cd /usr/local/share/npm-global/lib/node_modules/@anthropic-ai/claude-code
展開されたcli.jsが存在しているので、その中でMAX_THINKING_TOKENS周りのロジックを取り出します。
grep -R -n 'MAX_THINKING_TOKENS' . 2>/dev/null
ちなみにこんな感じで取れます。Thinkキーワードのローカライズ周りの実装も見えますね。
このままだと到底読めないので、コピペしてClaudeにロジックを解析してもらいました。
処理フローだけ抜粋：
1. 入力解析
ユーザーメッセージの内容を小文字に変換
テキストコンテンツを抽出
各言語のパターンと照合
2. パターンマッチング
HIGHEST レベルのパターンを最初にチェック
見つからない場合は MIDDLE レベルをチェック
最後に BASIC レベルをチェック
どれも該当しない場合は NONE (0トークン)
3. トークン配分
環境変数 MAX_THINKING_TOKENS が設定されている場合は優先使用
パターンマッチングの結果に基づいてトークン数を決定
テレメトリーでトークン使用量を記録
Claudeの解析全文も一応公開しておきます
まとめ
この記事では、改めてClaude Codeのultrathink周りについて調べました。
- 常に
ultrathinkする方法 -
MAX_THINKING_TOKENSによる思考トークン固定 - 思考トークン予算の割り振りに関する注意点
少しでも参考になれば幸いです。
𝕏フォローしてくれると嬉しいです！
𝕏でも情報発信しているので、フォローしていただけると励みになります！
最近のAI関係のポストは、ハイライトを見ていただければと思います。
参考文献
Views: 0
