Claude Codeのサブエージェントをeffort指定で走らせる方法

Claude Codeのサブエージェントは、Agentツールのeffortパラメータで1回の呼び出しごとに推論の深さを変えられます。Claude Code v2.1.292以降の機能です。サブエージェント定義のeffortフロントマターより強く、CLAUDE_CODE_EFFORT_LEVEL環境変数より弱い。この順序を押さえれば、「指定したのに効かない」の大半は説明がつきます。

effortの決まり方を3層で見る

サブエージェントのeffortには、指定できる場所が3つあります。強い順に並べると次のとおりです。

その下に、/effortや--effortで決めたセッションのレベルと、モデルの既定値が続きます。

3層の違いは「誰が、いつ決めるか」です。環境変数は設定した人が全体に効かせ、フロントマターは定義の作者が役割ごとに決めます。パラメータは、その場の依頼で個別に決まります。

Agentツールのeffortパラメータは何を変えるか

effortパラメータは、Claudeがサブエージェントを起動するときに渡せる引数です。ユーザーが直接入力する欄はなく、「このサブエージェントはlowで走らせて」のように依頼して、Claudeに渡してもらう形になります。

変わるのは、その呼び出しで動くサブエージェントの推論の深さです。定義ファイルを書き換える必要はありません。同じcode-reviewerでも、軽い確認ならlow、設計に踏み込む査読ならhighと、依頼ごとに振れます。

挙動は4点です。

• フロントマターのeffortより優先される
• 再開(resume)したサブエージェントにも引き継がれる
• CLAUDE_CODE_EFFORT_LEVELが設定されていると、そちらが勝つ
• forkには指定できない(対象は非forkのサブエージェント)

再開に残る点は、モデル指定と同じ扱いです。modelパラメータもresume後に維持されます。モデルの決定順はCLAUDE_CODE_SUBAGENT_MODELで触れているとおりで、effortはその別系統になります。

依頼文の例と定義ファイルの書き方

呼び出し側の依頼は、次のように書けます。公式の例ではなく、パラメータの仕様に沿った依頼文の一例です。

code-reviewerサブエージェントをeffort lowで走らせて、
src/auth/ の変更に明らかな問題がないか確認して

定義ファイル側で既定を決めておく場合は、フロントマターに書きます。

---
name: code-reviewer
description: Reviews code changes for correctness
tools: Read, Grep, Glob
effort: medium
---
 
You are a code reviewer. Check the diff for correctness bugs.

この定義なら、何も指定しないときはmediumで動きます。「今回だけlowで」と頼めば、その呼び出しだけlowに下がります。同じ依頼で「今回は深く」と頼めば、highやxhighに上げることもできます。定義の既定は、パラメータが無い呼び出しの保険として働きます。

指定できる値はlow、medium、high、xhigh、maxです。使えるレベルはモデルで違い、Opus 4.6とSonnet 4.6にはxhighがありません。非対応のレベルを指定すると、そのモデルが対応する最も近い下のレベルで走ります。たとえばOpus 4.6のxhighはhighとして実行されます。

指定が効かないときの切り分け

「lowと頼んだのに深く考えている」ときは、次の順で確かめます。

確認には/tasksが使えます。実行中のサブエージェントの行にモデル名が出て、そのサブエージェントにeffortが設定されていれば値も添えて表示されます。この表示はv2.1.242以降が対象です。

claude --version
echo "${CLAUDE_CODE_EFFORT_LEVEL:-未設定}"

1行目でv2.1.292以降かを、2行目で環境変数の有無を確かめられます。シェルで空でも、settingsのenvブロックで設定されている場合があります。

モデル指定とeffort指定の扱いの違い

Agentツールにはmodelパラメータもあり、effortと似た形で使えます。ただし、環境変数との関係や、forkでの扱いが揃っているわけではありません。

モデルは、許可リストなどで通らないと、同じ系統の許可されたモデルか継承モデルで実行されます。effortは、モデルが対応しないレベルを指定すると、そのレベル以下で対応する最も高いレベルで実行されます。「頼んだのに違うレベルで走っている」ときは、モデルが対応するレベルを先に確かめると原因が絞れます。

thinkingはeffortと別に決まる

推論に関する設定は、effortのほかにextended thinkingがあります。サブエージェントのthinkingは、v2.1.198以降はメインの会話の設定を引き継ぎます。セッションでthinkingがオンならサブエージェントでもオン、オフならオフのままです。サブエージェントごとにthinkingを切り替える設定はありません。

そのため、effortをlowにしても、thinkingそのものがオフになるわけではありません。逆に、サブエージェントだけthinkingを切って軽くする手もありません。軽くしたい場合に使えるのは、effortを下げるか、モデルを小さいものに変えるかの2つです。v2.1.198より前は、メインの設定にかかわらずサブエージェントのthinkingは無効でした。古いバージョンで挙動が違うと感じたら、この変更が理由かもしれません。

使いどころ: 軽い確認はlow、判断が重い作業はhigh

effortは推論の深さを調整するもので、下げれば速く安く、上げれば深くなります。サブエージェントを並列で複数走らせる構成では、1本ごとの差が積み上がります。

これは使い分けの考え方の一例で、公式が数値で推奨しているわけではありません。

effortレベルの基本にあるとおり、既定値はモデルごとに違います。Opus 5.5、Sonnet 5.5、Haiku 5.5はmedium、Opus 4.7はxhigh、そのほかはhighです。サブエージェントのモデルを下げて単価を抑える設計はモデル配分の記事で扱っています。モデルを変えずに思考量だけ下げたいときに、effortパラメータが選択肢になります。

なお、Haiku 4.5のようにeffortに対応しないモデルでは、指定しても働きません。対応モデルの一覧には載っていないためです。

毎回頼まなくて済ませるには

同じ役割で毎回同じeffortを使うなら、パラメータで頼み続けるより定義ファイルに書くほうが安定します。CLAUDE.mdに運用ルールを書いておく方法もあります。

## サブエージェントの運用
- ファイル検索・一覧化だけのサブエージェントは effort low で起動する
- 設計レビューを任せるサブエージェントは effort high で起動する

CLAUDE.mdの指示はClaudeが守る規約で、設定のような強制力はありません。確実にしたい場合は、フロントマターに書きます。全体を一律に固定したい場合はCLAUDE_CODE_EFFORT_LEVELですが、これはサブエージェントだけでなくメインの会話にも効く点に注意が要ります。/effortや--effortでも変えられなくなります。

セッション全体のeffortを保存する場所はmodelSettingsにあります。サブエージェントのパラメータはこの保存値とは独立して、その呼び出しだけに効きます。

v2.1.292の変更点との関係

changelogのv2.1.292(2026年10月6日)には「Agentツールにeffortパラメータを追加し、Claudeが依頼されたeffortレベルでサブエージェントを実行できるようにした」とあります。リリース全体の変更はClaude Code v2.1.292のリリースノートにまとまっています。

まとめ

サブエージェントのeffortは、環境変数、パラメータ、フロントマターの順に強く、環境変数が設定されていると呼び出し単位の指定は効きません。効かないときは、環境変数、forkかどうか、上限設定、バージョンの順に見ると切り分けられます。役割ごとの既定は定義に、その場の例外はパラメータにという分担にすると、依頼の手間が減ります。