Claude Code 使い方ガイド：maxEffortLevelで推論レベルを制御

Claude Code 使い方：まず押さえる上限設定

Claude Code 2.1.267以降へ更新し、管理したい人とプロジェクトの範囲に合う設定ファイルに "maxEffortLevel": "medium" を追加します。自分の全リポジトリに共通する上限なら ~/.claude/settings.json、一つのリポジトリで作業する全員に適用するなら .claude/settings.json、組織全体のルールならマネージド設定を使います。

指定できる値は low、medium、high、xhigh、max です。max は、その設定元ではエフォートに上限を設けないという意味です。キーを設定しない場合も上限はありません。

これは速度制限であって、利用枠ではありません。リクエストごとにClaudeがどこまで深く推論できるかを制限しますが、トークン枠、金額の予算、サブスクリプションの利用上限は設定しません。それらは /usage、Claude Console、または Claude Code OpenTelemetry で別に計測してください。

maxEffortLevel が実際に変えるもの

effortLevel と maxEffortLevel の役割は異なります。エフォートレベルは、セッションまたはモデルに対して要求する設定です。最大エフォートレベルは、その要求が越えられない境界です。

上限が medium なら、開発者は引き続き low または medium を選べます。high、xhigh、max を要求しても、実際の実行は medium になります。この上限は、/effort、/model の選択画面、--effort、CLAUDE_CODE_EFFORT_LEVEL、モデルのデフォルトから要求されたエフォートにも適用されます。Claude Codeは各リクエストの送信前にクライアント側で上限を適用するため、モデルへの通信がAnthropic、Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundryのいずれを経由しても、同じポリシーが機能します。

見落としやすい重要なルールは、読み込まれたすべてのスコープのうち、最も低い上限が採用されることです。通常のClaude Code設定には優先順位があり、マネージド設定がコマンドライン設定、プロジェクトファイル、ユーザー設定より上位になります。しかし maxEffortLevel は、より厳しい値を優先する例外です。マネージド設定やユーザー設定がより高いレベルを許可していても、プロジェクト側の低い上限が有効になります。

Claude Code 設定：全体上限、モデル別例外、より厳しいプロジェクト上限

まず claude --version を確認します。2.1.267より古ければ、キーを追加する前に claude update を実行してください。

すべてのリポジトリに共通する個人用の上限は、~/.claude/settings.json に次のように記述します。

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

トップレベルの値により、対応するすべてのモデルが medium 以下に制限されます。Sonnet 4.6の項目は、このユーザーファイル内に限り、Sonnetに対するトップレベル値を置き換えます。ここでの max は、Sonnetを最大エフォートで強制実行する指定ではありません。この設定元では、そのモデルに上限を課さないという意味です。

次に、一つのリポジトリへさらに厳しいルールを追加します。.claude/settings.json は次の内容です。

{
  "maxEffortLevel": "low"
}

意図どおり、実効結果は厳しくなります。

モデル別の例外がプロジェクトルールを突き抜けることはありません。解除されるのは、ユーザー設定元がSonnetに課すmediumの上限だけです。この点を誤ると、例外が全面的に効いていると思い込みやすくなります。

会社のポリシーとして導入する場合は、同じトップレベルのキーをマネージド設定で配布します。そのマネージド設定の対象者には、対応するどのプロバイダーでも上限が適用されます。Enterpriseロール側にもエフォート制限がある場合、Claude Codeは両者のうち低い上限を採用します。

上限を信用する前に実効値を確認する

JSONが正しいだけでは、意図した上限が優先された証明にはなりません。読み込まれた設定元と、実際に適用されたレベルの両方を確認します。

1. Claude Code内で /status を実行します。Setting sources の行を見れば、User settings、Project settings、Managed settingsが読み込まれたかを確認できます。ただし、個々のキーがどの設定元から来たかまでは分かりません。
2. 設定元が見つからない場合や、新しいキーが無視されているように見える場合は、claude doctor を実行します。拒否された設定項目が一覧表示されます。公開JSONスキーマの更新がCLIの新リリースより遅れることがあるため、エディターの警告だけで判断しないでください。
3. モデル名の横にあるセッションヘッダーを確認します。Claude Codeは現在のエフォートをそこに表示し、変更時にはフッターにも短時間表示します。
4. 上の例のリポジトリで /effort max を要求します。それでもプロジェクトレベルの low 上限が適用されます。より高いレベルを要求しても引き上げることはできません。
5. 非対話型のフリートでは、claude_code.cost.usage と claude_code.token.usage の effort 属性を確認します。各リクエストに適用されたレベルが、モデルやクエリ元とともに記録されています。

最後の確認は、Bedrock、Google Cloud、Foundryで特に重要です。ポリシーはプロバイダーがリクエストを受け取る前にClaude Codeが適用し、テレメトリーにはClaude Codeが実際に適用した値が残ります。

品質と支出は別々の軸でテストする

mediumやlowという名前が節約向きに見えるという理由だけで導入してはいけません。チームがすでに把握している日常タスクを使い、条件をそろえた実行を比較します。

扱いやすいテスト用データは、失敗しているパーサーテストが一つある小規模リポジトリです。各実行でモデル、コミット、プロンプト、権限、ツールアクセスを同一にし、エッジケースを修正して回帰テストを追加し、テストスイートを実行したうえで変更ファイルを報告させます。上限なしのベースラインを実行し、テスト用リポジトリをクリーンな状態へ戻してから、上限ありの条件を実行します。

コストを見る前に結果を採点します。

判断基準にすべきなのは、レスポンス当たりのトークン数ではなく、受け入れられたタスク当たりのコストです。低エフォートの実行で二度目のレビューや修正が必要になれば、一度で完了する高エフォートの実行より高くつくことがあります。より広い Claudeのエフォートレベル比較 にも同じ考え方が当てはまりますが、この新設定により、選んだ上限をClaude Codeで強制できるようになりました。

エフォート上限が効果を発揮する七つの場面

誰が最も明確な運用効果を得られるかという観点で、以下のユースケースを並べています。

1. 日常業務を統制するプラットフォームチーム

20人または200人の開発者を支援するプラットフォームチームなら、マネージド設定で medium を指定し、より低いレベルは選択可能なままにして、計測で妥当性を確認した例外だけにポリシー変更を認められます。効果はトークン削減だけではありません。ノートPC、IDEセッション、クラウドプロバイダーへの経路をまたいで一貫したデフォルト境界ができるため、コストと品質を実用的に比較できます。

2. API課金のClaude Codeを管理するFinOps担当者

FinOps担当者は、マネージド上限と、effort、モデル、チーム、コストセンター別に集計したOpenTelemetryを組み合わせられます。流れは明快です。上限なしのベースラインを観測し、パイロットグループに上限を導入して、受け入れられたタスク当たりのコストを比較します。どのエフォートレベルが高く感じるかという議論を、完了した仕事にひもづくレポートへ置き換えられます。

3. Bedrock、Google Cloud、Foundryを利用する企業

規制対象の企業では、調達やデータ管理の要件から、選定したクラウド経由でモデルを利用することがあります。Claude Codeクライアントは各リクエストの送信前に maxEffortLevel を適用するため、組織は各プロバイダーで同じエフォートポリシーを使えます。プロバイダーごとの管理画面に同じ制御機能がそろうのを待たずに、ポリシーを統一できます。

4. 反復的な修正を走らせるCI管理者

依存関係の更新、フォーマット修正、テスト保守、ドキュメント変更にClaude Codeを使うチームなら、対象リポジトリを low または medium に制限できます。適切なレベルはタスク用のテストデータから決めるべきですが、品質を維持できると確認した後は、フラグ、スキル、モデルのデフォルトによって日常的な自動処理が深い推論モードへ上がるのを防げます。

5. 日常作業と難しい作業を分けるモノレポ管理者

モノレポの管理者なら、個人用の medium 上限を維持しつつ、ドキュメントや生成コードのリポジトリにはさらに低い共有上限をコミットし、難度の高いシステム用リポジトリでは広い上限を残せます。境界はリポジトリごとに保持されます。開発者全員がコマンドを覚えておくことに頼らず、作業内容に追従するコストポリシーを実現できます。

6. 顧客リポジトリを切り替えるコンサルティング会社

コンサルタントは、個人用のmedium上限を基準にし、顧客ごとのリポジトリでは必要に応じて、より厳しい共有設定を課せます。同じノートPCで小規模なコンテンツサイト、成熟したアプリケーション、コスト重視の保守契約を切り替える際の設定ずれを減らせます。プロジェクトファイルが、次の担当者に想定運用モードを伝える資料にもなります。

7. 限定的なモデル例外を維持するスタッフエンジニア

スタッフエンジニアは、modelSettings を使って一つのモデルを設定元の全体上限から除外しながら、安全性が重要なリポジトリには別の低い上限を残せます。その設定元が許す場所ではモデルに余力を与えつつ、例外が全体的な迂回路になるのを防げます。より厳しいプロジェクトまたは組織ポリシーに従う、範囲の明確な例外を作れるのが利点です。

この上限を軸に作る価値があるもの

1. 最有力はエフォート回帰ゲート

リポジトリの受け入れ済みタスク群を、許可された各エフォートレベルで実行し、合格率、レビュー上の欠陥、所要時間、トークン、コストを報告するCLIとCIチェックを構築します。上限を導入すると、「修正作業によって節約分が消える前に、日常タスクのエフォートをどこまで下げられるか」という品質上の問いがすぐに生まれるため、エンジニアリングプラットフォームチームには支払う理由があります。

商用需要のシグナルはとりわけ強力です。ai code review の米国における推定検索数は月間1,300件で、CPCは$62.38です。販売可能な最小構成は、同じクリーンなテスト用リポジトリで二つのエフォートプロファイルを比較し、必須テストまたはレビュールールに回帰があればポリシー変更を止める、ローカルランナーとGitHubチェックです。

難所はベンチマークです。汎用的なコーディングスコアは模倣しやすく、購入者のリポジトリとの結びつきも弱くなります。防御力になるのは、チーム固有の非公開タスク群、レビュー基準、モデル更新をまたいだ履歴です。そのデータがなければ、単なるダッシュボードにすぎません。

2. Claude Codeエフォートポリシーリンター

ユーザー、共有プロジェクト、プロジェクトローカル、コマンドライン、マネージドの各設定元を、モデル別の上限表へ整理する読み取り専用のポリシー検査ツールを構築します。max の例外が全体に効くと誤認されている状態、想定外に優先される低いプロジェクト上限、2.1.267より前のバージョンが残るフリートを検出できるため、プラットフォームチームやセキュリティチームに有用です。

claude code の米国における推定検索数は月間550,000件で、実際の質問群には「What effort level should I use for a Claude code?」も含まれます。この検索量は広範で、すぐ購入につながる層に限られるわけではありませんが、設定をめぐる混乱は明白です。MVPに必要なのは、設定元の検出、バージョン確認、JSON検証、最も低い上限が優先される理由の説明だけです。

難所はプラットフォーム側の変化です。Anthropicが実効設定を確認するネイティブ機能を追加する可能性があります。長く使われる製品にするなら、見やすい設定画面だけでなく、ポリシーずれの通知、フリートのインベントリー、監査用の証跡が必要です。

3. エフォート対応のClaude Code支出モニター

適用された effort 属性を、Anthropicおよびクラウドプロバイダー経由の導入環境全体で、トークン、コスト、モデル、クエリ元、リポジトリ、品質チェックと結合する専用OpenTelemetryダッシュボードを構築します。FinOpsチームと開発者体験チームが対価を払うのは、単なるトークン合計ではなく、ポリシーと成果を結びつける機能です。

llm observability の米国における推定検索数は月間590件で、CPCは$37.45です。既存製品の価格からも予算枠を確認できます。Datadog Agent Observabilityは40,000 LLM spansまで無料で始められ、Proは100,000 spansで月額$160からです。特化型MVPなら、OpenTelemetry collectorのプリセット、上限のインベントリー、適用エフォート、受け入れられたタスク当たりのコスト、モデルまたはポリシー変更後の回帰という三つのビューを提供できます。

難所は競合と因果関係です。Observabilityベンダーはすでにトークンとコストを収集しており、上限導入後に請求額が下がっても、それだけでは上限が原因だと証明できません。信頼を得るには、条件をそろえた評価または変化点の証拠が必要です。

この三案では、エフォート回帰ゲートが最良です。有料のエンジニアリング判断に最も近い需要があり、Anthropicがモデルやエフォートの調整を変えるたびに、非公開の評価履歴の価値が高まります。

上限では解決できないこと

エフォート上限は、請求額の減少を保証しません。エフォートは出力トークン、ツールの挙動、思考に影響しますが、モデルの選択、コードベースの規模、キャッシュの挙動、並列自動化も依然として重要です。Claude MaxとProの契約者はプラン内に利用量が含まれるため、/usage に出るセッションコストが請求額になるわけではありません。

また、すべてのコーディングタスクで low が安全になるわけでもありません。Anthropicはワークロードをテストするよう明確に推奨しており、同じエフォート名でもモデルごとに調整が異なります。あるモデルの medium は、別のモデルの medium と機械的に比較できる固定量の推論ではありません。

特定モデル向けの絶対的な迂回路も作れません。モデル別の max 設定で外せるのは、同じ設定元にあるトップレベル上限だけです。別の設定元がさらに低い上限を課すことがあり、組織のエフォート制限はそれより低い場合もあります。

最後に、/status で確認できるのは読み込まれたファイルであり、キーごとにどのファイルが優先されたかではありません。自動化では、テレメトリーの effort 属性のほうが、適用値を示す明確な記録になります。

来週実行すること

来週、日常的なリポジトリタスクを一つ選びます。上限なしのベースラインを記録し、ユーザーレベルに medium 上限を追加して、説明したSonnetの例外も設定したうえで、共有プロジェクトファイルに low を入れます。設定元が読み込まれたこととセッションヘッダーのエフォートを確認し、同じクリーンなテスト用リポジトリからタスクを再実行して、/usage のコストを見る前に受け入れ品質を比較します。品質を維持できたら、検証済みの上限を適切な共有スコープまたはマネージドスコープへ昇格させます。失敗した場合は、そのワークロードで最も厳しい上限を引き上げるか外し、検証結果は保存してください。

エンジニアリングワークフローに合わせて、エフォートポリシー、評価ゲート、コストテレメトリーを構築したい場合は、AI本番システム をご覧ください。