Claude Codeを長時間動かしていると、いつの間にか重い推論を選んでいることがあります。
調査では高いeffort levelを使いたい。でも、定期実行の確認や小さな修正まで同じ設定で動かす必要はありません。ここを毎回手で戻すのは面倒です。
2026年9月9日のClaude Code v2.1.267で、maxEffortLevelという設定が追加されました。トップレベル、またはモデルごとのmodelSettingsに上限を置けます。
今回は、公式変更履歴で確認できた範囲をもとに、この設定をどう使い分けるかを整理します。設定の細かい配置や利用できる値はバージョンで変わる可能性があるので、最後に必ず現在のドキュメントも確認してください。
effort levelは何を変えるのか
Claude Codeには、回答や作業にどれくらい推論の力を使うかを調整するeffort levelがあります。
短い質問や単純なファイル確認なら、毎回いちばん重い設定を使う必要はありません。逆に、複数ファイルの設計や原因調査では、より高いeffortを選びたい場面もあります。
ここで困るのが、上限を決めないまま自動化するケースです。
claude -p "リポジトリの状態を確認して、必要ならテストを実行してください"このような一回限りの確認なら、推論の上限を低くしても困らないことがあります。ところが、同じ起動経路で設計作業まで実行すると、必要以上に重い処理を選ぶ可能性があります。
私は、無人で回す処理ほど上限を設定した方が安全だと思います。使う力を下げる判断を毎回人間に任せると、忙しい時ほど忘れるからです。
maxEffortLevelで上限を置く
v2.1.267では、maxEffortLevelを設定できます。公式変更履歴の説明では、トップレベルまたはモデル単位のmodelSettingsに置き、各プロバイダーでeffort levelの上限として働きます。
設定のイメージは次のようなものです。
{
"maxEffortLevel": "medium"
}この例では、指定した上限を超えるeffort levelを使わせない、という考え方になります。ユーザーがそれより低いeffort levelを選ぶことはできます。
つまり、設定の役割は「常にmediumで固定する」ではありません。「mediumより上は選ばせない」です。ここを取り違えると、低いeffortまで禁止されるように見えてしまいます。
上限と固定は違います
上限を置くと、すべての処理が同じ重さになるわけではありません。
たとえば上限をhighにしても、簡単な処理までhighで実行されるという意味ではありません。どのeffort levelを使うかは、その時の選択や設定に依存します。highを超える指定だけを止める境界です。
逆に、毎回必ずlowで動かしたいなら、上限設定だけでは目的を満たしません。固定したいのか、上限だけ決めたいのかを分けて考えてください。
// 上限を決める考え方
{
"maxEffortLevel": "medium"
}
// 低い設定を選ぶかどうかは、別の設定やその時の操作で決まるこの境界は地味ですが大事です。設定名にmaxが入っているので、最大値の固定だと考えがちです。実際には「これ以上は使わない」という安全弁です。
モデル単位で上限を分ける
モデルごとに運用を変えたい場合は、modelSettings側に上限を置く考え方があります。
{
"modelSettings": {
"model-a": {
"maxEffortLevel": "medium"
},
"model-b": {
"maxEffortLevel": "high"
}
}
}ただし、ここに書いたモデル名や設定の組み合わせが、使用中のClaude Codeでそのまま有効になるかは、現在の設定リファレンスで確認してください。公式変更履歴から確認できるのは、モデル単位の設定にも上限を置けるという追加内容です。
モデル名を適当に書いて動作確認したことにするのは危険です（この例は設定の考え方を示すためのものです）。実際の環境では、/configや設定ドキュメントで利用できる形式を確認してから保存しましょう。
無人ループではどこに効くか
私がこの設定を使いたいのは、定期実行や検収のような処理です。
python tools/fetch_metrics.py --days 7 --json
python tools/cws_check.pyこの種の仕事は、決められたコマンドを実行して結果を記録するものです。大きな設計判断を求めているわけではありません。
それでも、同じセッションで記事執筆や複雑な調査を続けると、実行全体の重さが読みにくくなります。上限を設定しておけば、軽い確認が必要以上に膨らむのを抑えられます。
ここで注意してください。maxEffortLevelは、ツールの失敗を直してくれる設定ではありません。ネットワーク障害や権限拒否、間違ったコマンドは別に検出する必要があります。
上限を下げたから検収が不要になるわけでもありません。実際のファイルやAPIの結果を読み直すところまでが仕事です。
記事執筆や設計では上限をどうするか
記事の構成を考えたり、公式資料を複数比較したりする時は、軽い設定だけでは足りない場合があります。
そのため、私は作業の種類ごとに設定を分けます。
- 死活確認、メトリクス収集、ログ整理は低めの上限
- 複数の公式資料を突き合わせる調査は中〜高めの上限
- 設計や大きなリライトは、必要な時だけ高めにする
全部を高くするのは簡単です。でも、それでは上限設定の意味がありません。重い仕事だけ上限を上げる方が、何を大事にしているかも分かりやすくなります。
反対に、上限を低くしすぎると、記事の根拠確認や長いコードの読み取りで取りこぼしが出る可能性があります。数字を小さくすれば必ず良い、という話でもありません。
では設定を確認してみましょう
まず、使用中のClaude Codeがv2.1.267以降かを確認します。
claude --versionバージョンが表示されたら、次に設定の現在値を確認します。設定ファイルをいきなり書き換えるのではなく、まずClaude Codeの設定画面と公式ドキュメントで、使用中の形式を確認してください。
公式変更履歴の内容をもとに、トップレベルの設定を試すなら次のような最小構成から始めます。
{
"maxEffortLevel": "medium"
}設定を保存したら、単純な確認を1回だけ実行します。ここでいきなり大きなリポジトリ操作を任せるのはやめましょう。
claude -p "現在の作業ディレクトリにあるファイルを3つだけ確認して、名前を出してください"期待した処理が動いたら成功です。表示された値や設定の読み込み結果が、実際の環境と合っているか確認してください。
もし設定エラーになった場合は、バージョン差や設定ファイルの場所を確認します。maxEffortLevelの名前だけを見て、別の設定名に置き換えるのはやめた方がよいです。存在しない設定を作ると、効いているつもりのまま運用してしまいます。
v2.1.267には別の変更もあります
v2.1.267ではmaxEffortLevelだけでなく、--system-prompt-snapshot offも追加されています。
こちらは、会話に記録されたシステムプロンプトを再利用せず、リクエストごとに新しく描画するためのオプションです。プロンプト文面を試行錯誤するときに使う機能として説明されています。
どちらも、設定や実行条件を明示して再現性を上げる方向の変更です。ただし、役割は違います。
maxEffortLevelは、推論の重さに上限を置く--system-prompt-snapshot offは、システムプロンプトの再利用方法を変える
まとめて設定したくなりますが、最初は1つずつ試してください。何が変わったのか分からなくなるからです。
上限設定だけではコスト管理にならない
maxEffortLevelはコストや処理時間を直接表示する機能ではありません。上限を置いても、リクエスト数が増えれば利用量は増えます。
長いログを何度も読み込ませれば、effort levelを抑えていても重くなります。不要なファイルを対象にしない、結果をファイルに保存する、完了したユニットを再実行しない。この運用の方が効く場面も多いです。
私の場合は、設定を安全弁として使い、実行単位とログの管理を別に持ちます。設定1つで全部を解決しようとしない方が、後から原因を追いやすいです。
まとめ
Claude Code v2.1.267のmaxEffortLevelは、effort levelの上限を設定する機能です。
トップレベル、またはモデルごとのmodelSettingsに置けます。指定した上限より低いeffort levelは選べますが、上限を超える指定は抑えられます。
定期実行や小さな確認では低めの上限を使い、設計や深い調査では必要な範囲だけ上げる。この使い分けが現実的です。
ただし、設定が効いているかは必ず確認してください。バージョンや設定形式が違えば、書いたつもりの値が無視されることもあります。私はまず小さなコマンドで試して、実際の表示とログを確認します。
重い処理を使うかどうかを毎回の気分に任せない。上限を決めておくだけで、無人実行の事故は減らせます。これ、意外と使えます。
コメント