Effort と ultracode — 賢さ・徹底度をコントロールする

「頑張り度」というツマミ — effort とは (What is Effort)

ch4-l3 では思考トークン数を budget_tokens で指定する Extended Thinking を学びました。 Claude 4.7 以降と Claude 5 世代では、この考え方が一新されています。

• 思考のオン/オフや量は、モデル自身が判断する adaptive thinking (適応思考) へ
• 人間が握るのは effort (エフォート) — 「どれだけ深く考え、どれだけトークンを使ってよいか」の 頑張り度のツマミ

effort が変えるのは思考の深さだけではありません。低くすると ツール呼び出しが少なくまとまり、前置きが減り、確認も簡潔 になる——つまり 行動全体の徹底度 が変わります。ベータヘッダー不要の正式機能 (GA) です。

基本の書き方 (How to Set Effort)

output_config の中に書きます。トップレベルのパラメータではない 点に注意。

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},        # Opus 4.8 では明示が必要 (省略すると思考オフ)
    output_config={"effort": "high"},     # ← ここ。low / medium / high / xhigh / max
    messages=[{"role": "user", "content": "..."}],
)

• 未指定なら high として扱われる (= 省略と同じ)
• thinking の既定はモデルで異なる: Opus 4.8 は明示が必要、Sonnet 5 は省略でも adaptive、Fable 5 は常時オン (thinking 自体を書かず effort だけで OK)

5 段階の使い分けガイド (Choosing a Level)

モデル別の対応状況

モデル別のクセ

• Fable 5: effort が知能・時間・コストの 主制御。low でも 旧世代の xhigh / max 級 の結果が出ることがあり、「正しく終わるが時間がかかりすぎる」タスクは下げるのが正解
• Sonnet 5: レベルを 忠実に守る。目安として Sonnet 5 の medium ≈ Sonnet 4.6 の high、Sonnet 5 の high ≈ Sonnet 4.6 の max
• Opus 4.8: 反射的に xhigh にせず high から始めて掃引 (sweep) が公式推奨。max は超難問かつ時間に寛容な場面だけ

🎯 持ち帰りは 3 つだけ: 既定は high / コーディング・エージェントは xhigh / 正確性最優先のときだけ max。 推論が浅いと感じたら、プロンプトで「よく考えて」と粘るより effort を 1 段上げる のが先です。

budget_tokens から effort へ (Migration)

ch4-l3 の budget_tokens 方式は Opus 4.6 / Sonnet 4.6 で非推奨、Opus 4.7 以降と Claude 5 世代では 400 エラー になります。

# 旧 (〜4.6 世代): 思考トークン数を直接指定
thinking={"type": "enabled", "budget_tokens": 4000}

# 新 (4.7 以降 / Claude 5 世代): 深さのレベルを指定
thinking={"type": "adaptive"},
output_config={"effort": "high"},

「何トークン考えるか」を人間が数字で決める時代から、「どのくらい本気を出すか」だけ伝えて配分はモデルに任せる時代へ。1:1 の対応表はないので、移行時は評価セットで再調整します。

コスト・品質・時間の三角関係 (The Tradeoff Isn't Linear)

「高 effort = 高コスト」とは限りません。エージェント作業では、高 effort が最初に賢く計画する分 手戻りが減り、往復回数ごと減って総コストが下がる ことがあります。逆に max は考えすぎで遅く冗長になる (収穫逓減) ことも。

実務のチューニング手順:

1. medium / high / xhigh を 自分の評価セットで掃引 する
2. 品質・時間・トークン消費の 3 つを 数字で 比べる (勘で決めない — ch2-l5 の eval-driven と同じ発想)
3. ルート (処理の種類) ごとに最適レベルを固定する
4. xhigh / max を使うときは max_tokens に余裕を (64K 目安 + ストリーミング)。思考の途中で出力枠が尽きるのを防ぐ

Claude Code の /effort (Effort in Claude Code)

Claude Code にも同じ 5 段階があり、既定は xhigh (コーディング向けの推奨値がそのまま既定)。 セッション中に /effort コマンドでいつでも切り替えられます。

/effort
→ low / medium / high / xhigh / max から選択 (そのセッション限り)

• max を選ぶと最深の推論になる代わりに、応答が長時間化しトークン消費が増える 旨の注意が表示される。「ここぞ」専用
• 逆に軽い作業の日は medium に落とすとサクサク動く
• Claude Code が サブエージェント を起動するときは、役割に応じて低い effort が使われることもある — 「本体は深く、手足は速く」という設計思想

ultracode — 深さではなく「広さ」の総力戦

effort が 1 体の Claude がどれだけ深く考えるか のツマミなら、ultracode は Claude Code で 何体の Claude を並列に動かすか — 「広さ」の総力戦モードです。

プロンプトに ultracode という合言葉を含める (またはセッションで有効化する) と、マルチエージェント編成 (ワークフロー) の使用を明示的に許可したことになり、Claude Code はタスクを分解して 数十のサブエージェントに並列で調査・実装・検証 をさせます。

何が起きるか — 品質パターンの例

• 並列ファンアウト: 大きな調査・監査を次元ごとに分けて同時に走らせる
• 敵対的検証: 1 つの発見に対し複数の「反証役」を立て、生き残った指摘だけ採用する
• 多視点レビュー: 正しさ・セキュリティ・性能など別々のレンズで同じ対象を見る
• 尽きるまで探索: 新しい発見がゼロになるまで探索ラウンドを繰り返す

なぜ「合言葉」が必要か

エージェントを数十体動かせば トークン消費は桁違い になります。だからこそ勝手に発動せず、ユーザーの明示的なオプトイン が条件になっています。ultracode と書かなくても、「ワークフローを使って」「エージェントを並列に出して」と自分の言葉で頼めば同じ扱いです。

• ✅ 向いている: 網羅的なコード監査、大規模な調査・移行、見落としが許されない検証
• ❌ 不向き: 日常の小タスク (通常モードで十分。コストの無駄)

「ultra 系」用語の整理

⚠️ Claude Code の機能・名称はバージョンアップで変わりやすい領域です。手元の環境では /help と公式ドキュメントで最新の挙動を確認してください。

まとめ

• effort は output_config に書く 5 段階のツマミ。既定 high / コーディング・エージェントは xhigh / 正確性最優先だけ max
• budget_tokens は過去のもの — 4.7 以降 / Claude 5 世代では 400 エラー (adaptive + effort へ)
• 高 effort ≠ 常に高コスト。評価セットで掃引して数字で決める。xhigh / max は max_tokens 64K 目安 + ストリーミング
• Claude Code は /effort で切替 (既定 xhigh)。深さ = effort、広さ = ultracode — 別の軸
• ultracode は数十エージェントの総力戦。トークン消費が大きいので、網羅性が本当に要る場面だけオプトイン