Claude Code effort 思考量・reasoning レベルの使い方と実装設計ガイド

Claude Code の /effort とは何か ― 思考量を制御するコマンドの設計思想

Claude Code には /effort というスラッシュコマンドがあり、モデルが回答を生成する前に行う内部推論（reasoning）の深さと、それに伴うトークン消費量のバランスを手元で即座に切り替えられる。「思考量の調整つまみ」と言えばわかりやすいが、正確には「adaptive reasoning にどれだけのリソースを割り当てるかの上限設定」だ。応答品質・応答速度・API コストの三者すべてに直接影響する。

指定できるレベルは low / medium / high / xhigh / max / ultracode で、利用可能なレベルはモデルによって異なる。max と ultracode はセッション限定の上位設定だ。引数なしで /effort と入力すると対話式スライダーが起動し、/effort auto で既定値に戻せる。設定はコマンド実行直後から反映される。

ultracode は xhigh 相当の推論に加えて自動ワークフロー連携を行う特殊モードで、複数ツールを組み合わせた大規模タスクに向いている。一方、単純な修正や定型作業には low を選ぶと速く安く済む、という使い分けが基本的な考え方だ。

仕組みを理解しないまま運用すると、コストだけが膨らむか、複雑な推論タスクで精度が不足するかという両極端に陥る。本記事では、各レベルの特性・コマンドの使い方・コスト設計・限界の4点を実装者の視点から整理する。

low 高速・最低コスト

medium デフォルト

high 高精度・推論深化

max 最大推論・最高コスト

推論深度 深

コスト 高

Claude Code のインストール方法やプラン詳細については Claude Code のインストール手順 および Claude Code の料金プラン を参照されたい。

effort の各レベル詳細と使い分けの判断基準

各レベルの特性を整理する。以下はコミュニティの観測報告と公式ドキュメントの reasoning effort 仕様を組み合わせた整理だ。

Claude Code effort レベル比較

effort レベル	推論の深さ	トークン消費	応答速度	推奨ユースケース
low	最小限	最少	最速	コード整形・単純なリネーム・定型コメント生成・大量バッチ処理
medium（デフォルト）	標準的	標準	標準	一般的なバグ修正・機能追加・PR レビュー支援・ドキュメント生成
high	深い	多い	やや遅い	複雑なリファクタリング・設計判断・依存関係の影響分析・テスト設計
xhigh	より深い	かなり多い	遅い	難解なアルゴリズム設計・再現困難なバグ調査・大規模設計レビュー
max（セッション限定）	最大	最多	最も遅い	大規模アーキテクチャ変更・根本原因分析など一点集中の高価値タスク
ultracode（セッション限定）	xhigh 相当＋自動連携	最多クラス	最も遅い	複数ツールを組み合わせた長期・複合タスク

判断の基軸はシンプルだ。「この質問の答えを間違えると後工程でコストがかかるか」という問いに対して Yes なら effort を上げる。逆に「試行錯誤の初期段階でスピードが優先か」という場面では low または medium を選ぶ。

コミュニティの観測では、effort は Claude Code が「適応的推論（adaptive reasoning）」にどれだけリソースを割くかを制御するパラメータとして機能しており、低 effort では推論ステップが間引かれ、高 effort では多段階の検討が行われる。モデルと effort の2軸でコスト設計を考えることが実装上の基本となる（python-engineer.co.jp、2026年5月26日）。

なお、max および ultracode を常時使用すると、thinking tokens（内部思考に消費されるトークン）が大幅に増大し、API コスト・レイテンシが非線形に上昇する。特に Anthropic API 経由で従量課金している場合は thinking tokens の課金構造を把握した上で判断する必要がある（API コストの詳細は Claude Code API の料金体系 を参照）。

/effort コマンドの使い方と実践パターン

Claude Code ではスラッシュコマンド /effort でレベルをセッション中にいつでも変更できる。設定は即時反映され、その後のリクエストすべてに適用される。

# レベルを直接指定する
/effort low
/effort medium
/effort high
/effort xhigh
/effort max
/effort ultracode

# 引数なしで対話式スライダーを起動する
/effort

# 既定値（auto）に戻す
/effort auto

プロンプトで「簡潔に答えて」「深く考えて」と毎回お願いしなくても、/effort コマンドで一括制御できる点が実用上の強みだ。タスクが切り替わるたびにコマンドを打つ習慣をつけると、品質とコストの両方をコントロールしやすい。

スラッシュコマンドの全体像については Claude Code のスラッシュコマンド一覧 に詳述している。

CLAUDE.md でデフォルト effort を固定する

プロジェクトごとに effort の基準値を固定したい場合は、プロジェクトルートの CLAUDE.md に方針を記述する。Claude Code はセッション開始時にこのファイルを読み込み、エージェントの振る舞いの前提として扱う。

# CLAUDE.md
## Agent behavior
- Default effort: high
- Reasoning: Prioritize correctness over speed for all code changes

ただし、effort を常時 max や ultracode に固定すると、CI/CD パイプラインや大量バッチ処理で想定外のコスト増を招く。用途ごとに明示的に使い分ける設計が現実的だ。なお、CLAUDE.md に存在しないキーやフラグを記載しても無視されるか、エラーになる。設定項目は使用バージョンの公式ドキュメントで必ず確認してほしい。

Agent SDK からの effort 制御

Agent SDK を使う場合、Python / TypeScript のコードから reasoning effort に相当するオプションを渡せる。ClaudeAgentOptions でツール許可やモデル設定を制御できるが、effort に相当するパラメータの名称は SDK バージョンごとに変わりうるため、使用バージョンの公式リファレンスを必ず参照してほしい。以下は SDK の基本的な呼び出しパターンだ。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Refactor auth.py to use dependency injection",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
            # effort に相当するパラメータは使用バージョンの公式仕様に従って指定
        ),
    ):
        print(message)

asyncio.run(main())

なお、Agent SDK および claude -p のサブスクリプションプランでの利用は、インタラクティブ使用とは別の月次 Agent SDK クレジットから消費される仕様となっている（Anthropic 公式「Claude Code Agent SDK overview」）。CI/CD パイプラインで Agent SDK を活用している場合は、クレジットの消費状況を定期的にモニタリングすること。

タスクを受け取る

推論深度が 必要か？

No（定型・高速優先） low / medium

Yes（設計・複雑推論） high / max

コスト・レイテンシ 増大に注意

effort とコスト設計のトレードオフ ― 実装時に考慮すべき注意点

effort は「高いほど良い」という単純な指標ではなく、タスクの複雑度とコストのバランスを最適化するための制御弁として扱うべきだ。以下に実装設計上の注意点を整理する。

adaptive thinking との相互作用

Claude Code は effort と adaptive thinking を組み合わせて動作する。adaptive thinking は、モデルが問題の難易度を推定して思考トークンの使用量を動的に調整する仕組みだ。effort が medium の場合、adaptive thinking が有効であれば簡単なタスクでは少ない思考量で済み、複雑なタスクでは自動的に思考量が増える。effort を上げることは adaptive thinking が使用できる思考トークンの「上限」を引き上げる操作に近い。

この設計の実用的な意味は、「medium 設定のままでも複雑なタスクには自動的に多めのリソースを使う」ということだ。一方で adaptive thinking を無効化して effort max を固定すると、すべてのタスクで最大思考量が使われるため、シンプルなタスクでも高コストになる点に注意が必要だ。

モデル選択との組み合わせ

effort はモデル選択（Opus / Sonnet / Haiku）と独立したパラメータだが、両者の組み合わせで挙動は大きく変わる。Haiku で effort を max にしても Opus + effort high に比べて推論能力の絶対値は異なる。コスト最適化の観点では「Sonnet で effort を high にするか Opus で medium にするか」というトレードオフを検討することになる（python-engineer.co.jp、2026年5月26日）。モデル比較については Claude Code と Cursor の比較 および Claude Code と Codex の比較 も参考になる。

長大セッションでのコスト急増を防ぐ

effort を max や ultracode に固定したまま長大なコンテキストを持つセッションを続けると、thinking tokens の蓄積でコストが急増する可能性がある。公式ドキュメント（Anthropic 公式「Claude Code Common workflows」）でも、コンテキスト管理の手法として /clear によるリセットや CLAUDE.md を使った絞り込みが推奨されている。定期的にコンテキストをリセットするか、タスク単位でセッションを分割する運用が現実的だ。

品質劣化の誤診断を避ける

「Claude Code の品質が低下した」と感じたとき、その一因がデフォルト effort の変更である場合がある。「モデルが劣化した」と結論づける前に、まず /effort の現在の設定を確認することが診断の第一歩だ。/effort high や /effort xhigh に切り替えて品質が回復した場合は、effort の調整で対処できる（ai-native.jp、2026年4月25日）。

effort 設定の実運用ガイドライン ― タスク別推奨マトリクスと限界

実装現場での判断を助けるタスク別の推奨 effort をまとめる。タスクの性質に基づく定性的な推奨として提示する。

タスク別の推奨 effort レベル

タスク例	推奨 effort	選定理由
コードの整形・Lint 対応	low	ルールベースで機械的。多段階推論は不要
変数名・関数名のリネーム	low	検索・置換レベルの作業。推論深度を上げても品質は変わらない
ユニットテストの雛形生成	medium	既存コードのパターン理解が必要。adaptive thinking で自動調整される
バグ修正（再現条件が明確）	medium	原因特定と修正の両方でそこそこの推論を要するが、high 以上は過剰になりやすい
設計レビュー・アーキテクチャ提案	high	多面的なトレードオフ検討が必要。深い推論の恩恵が大きい
複雑な並行処理のデバッグ	high	因果関係の追跡に深い推論が必要。medium では見落としが出やすい
難解なアルゴリズム最適化	xhigh / max	数学的推論・複数候補の比較が必要。コストを払う価値がある場面
大規模リファクタリングの計画立案	max / ultracode	影響範囲の網羅的な把握に最大の推論量が必要。自動ワークフロー連携も有効

effort で解決できない問題とその限界

effort を上げることで改善できるのは推論の深さに由来する問題に限られる。以下のケースは effort 変更では解決しない。

• コンテキストウィンドウの不足：大量のファイルを同時に参照するタスクは、effort よりもコンテキスト管理（/clear や CLAUDE.md による絞り込み）が先決だ。公式ドキュメント（Anthropic 公式「Claude Code Common workflows」）でも、大規模コードベースでの文脈管理は専用のベストプラクティスとして別途解説されている。
• プロンプトの曖昧さ：指示が不明確な場合、effort を max にしても誤った方向への推論が深まるだけで精度は改善しない。前提条件・期待する出力形式・制約の3点を明示する習慣が先だ。
• モデル自体の知識カットオフ：最新ライブラリの API についての知識不足は effort では補えない。最新ドキュメントを fetch ツール等でコンテキストに注入する必要がある。
• ハルシネーション（事実の誤り）：推論量が増えると「もっともらしい誤答」として出力される可能性もある。effort を上げるほど誤答の確信度が高まるケースもあるため、出力の検証プロセスは別途必要だ。
• ツール実行権限の不足：effort はモデルの推論深度の設定であり、ファイルアクセス・コマンド実行などのツール権限とは独立している。権限不足による失敗は effort 変更では解決しない。

今後の仕様変更への備え