サブエージェントのeffortとは：何が決められるのか

effortは、モデルがどれだけ深く考えるかを調整する設定です。公式ドキュメントによると、低いeffortは速くて安く、高いeffortは複雑な問題に向く、と説明されています。サブエージェントは調査やレビューなどの作業を別の会話として任される仕組みなので、「調査は軽く、設計の判断は深く」のように役割ごとにeffortを分けられると、速さと費用の釣り合いを取りやすくなります。

指定できる段階はlow・medium・high・xhigh・maxですが、使える段階はモデルによって違います。

モデルが対応していない段階を指定すると、Claude Codeはそのモデルが対応する「指定以下で最も高い段階」に切り替えます。たとえばOpus 4.6でxhighを指定するとhighで動きます。

方法1：サブエージェントの定義ファイルに effort を書く

いちばん基本的な方法です。サブエージェントは~/.claude/agents/（全プロジェクト共通）または.claude/agents/（そのプロジェクトだけ）のMarkdownファイルで定義し、先頭のfrontmatterにeffortを足します。

---
name: code-reviewer
description: 変更差分をレビューする。コードを変更したあとに使う
model: sonnet
effort: high
---

あなたはコードレビュー担当です。……（以下、指示文）

公式ドキュメントでは、effortは「このサブエージェントが動くときのeffort」で、セッションのeffortを上書きします。ただし環境変数CLAUDE_CODE_EFFORT_LEVELは上書きできません。省略した場合は、後述する環境変数か、メインの会話の設定を引き継ぎます。

方法2：呼び出すときに effort を指定する

v2.1.292以降では、Claudeがサブエージェントを起動するとき、その1回の呼び出しだけにeffortパラメータを渡せます。ユーザーは、たとえば次のように頼みます。

code-reviewerサブエージェントを、effortをmaxにして起動して、この差分を見てもらって

公式ドキュメントの説明をまとめると、次のとおりです。

• このパラメータは、定義ファイルのeffortより優先される
• そのサブエージェントを再開（resume）したときも、指定したeffortのままになる
• 対象は「fork以外」のサブエージェント。会話を複製して分岐させるforkには使えない
• 環境変数CLAUDE_CODE_EFFORT_LEVELは、この呼び出し時の指定よりも優先される

「普段は定義ファイルのmediumで十分だが、今回だけ深く見てほしい」というときに向いています。

方法3：環境変数 CLAUDE_CODE_SUBAGENT_EFFORT で既定を決める

v2.1.316の更新履歴に、次の1行が追加されています。

つまり、定義ファイルにも呼び出し時にもeffortが無いサブエージェントの「既定値」を、環境変数で一括して決められるようになりました。たとえば、メインの会話は深く考えさせたまま、細かい調査を任せるサブエージェントは軽くしたい、という使い方が考えられます。

# 例：サブエージェントの既定を medium にして、Claude Codeを起動する
CLAUDE_CODE_SUBAGENT_EFFORT=medium claude

優先順位のまとめ：どの設定が勝つのか

公式ドキュメントの記載から確認できる範囲を、強い順に並べます。

4番目は更新履歴の文言からの読み取りで、公式ドキュメントに順位表があるわけではありません。また、メインの会話のeffortをCLAUDE_CODE_EFFORT_LEVELで固定していると、サブエージェントも含めてその値が最優先になる点に注意してください。サブエージェントだけ変えたいなら、この環境変数は使わないほうが安全です。

効いているかを確かめる：/tasks

サブエージェントが動いている間に/tasksを実行すると、各サブエージェントの行に、動いているモデルと、そのサブエージェントに設定されたeffortが表示されます（v2.1.242以降）。定義ファイルを書いたのに速さや回答の深さが変わらないときは、まずここでeffortが想定どおりかを見ます。

よくある質問（FAQ）

まとめ

まずは、いつも使うサブエージェントにeffortを1行足してみてください。