Claude Codeでサブエージェントのeffortを指定する方法｜v2.1.292以降の依頼の書き方

effortの指定で何ができるようになったか

これまでも、サブエージェントの定義ファイルにeffortを書けば、そのサブエージェントだけ考える深さを変えられました。ただし、定義ファイルを作っていない組み込みのサブエージェントや、作業ごとに重さが違う依頼では、細かく変えにくい面がありました。

v2.1.292では、Claudeがサブエージェントを起動するときに使うAgentツールに、effortの値が加わりました。定義ファイルを書かなくても、依頼文で深さを指示できます。

依頼文でのeffortの指定方法

Lydia Hallieが示した例は、「支払いAPIの呼び出しをlow effortのサブエージェントで全部探し、そのあとhigh effortの1体にエラー処理を確認させる」という依頼です。探す作業と確かめる作業で、深さを分けています。

日本語でも同じ形で頼めます。以下は編集部が作った例です。

このリポジトリで、決済APIを呼んでいる箇所をlow effortのサブエージェントで全部探してください。
見つかった箇所のエラー処理は、high effortのサブエージェント1体に確認させてください。
ファイルは編集せず、最後に問題のある箇所だけを一覧にしてください。

指定できる値は、モデルによって違います。モデル設定の公式資料によると、Opus 5.5、Sonnet 5.5、Haiku 5.5はlow・medium・high・xhigh・maxの5段階で、Claude Codeでの既定はmediumです。モデルが対応していない値を指定すると、その値以下で最も高い段階に下がります。

effortの指定について編集部が確かめたこと

編集部は10月8日、上の例と同じ狙いの依頼を、小さなPythonファイルを題材に1回実行しました。環境はClaude Code 2.1.293、Mac、claude.aiのアカウントでの接続で、メインのモデルはSonnet 5.5です。保存済みのstream-json形式の実行記録から、Agentツールの呼び出し内容を確認しています。ExploreとGeneral-purposeは、Claude Codeに最初から入っているサブエージェントの種類です。

依頼文で書いた深さが、そのまま呼び出しの値として渡されていました。Claude Codeが表示した費用は、定価で換算して約0.30ドルです（実際の請求額ではありません）。ただし、記録は1回だけで、lowとhighで質や速さがどう変わるかは測っていません。確かめられたのは起動時に渡された値までです。サブエージェントが実際にどれだけ考えたかは見ていません。

定義ファイルのeffortとの使い分け

同じ役割を何度も使うなら、定義ファイルに通常のeffortを置き、仕事ごとの例外を呼出し時に渡す方法があります。2026年10月10日に確認した公式資料は、非fork型では呼出し時の指定が定義ファイルより優先し、環境変数CLAUDE_CODE_EFFORT_LEVELが両方より優先すると明記しています。定義ファイルの指定はセッションのeffortより優先されます。呼出し時の指定は、そのサブエージェントを再開した後も維持されます。

---
name: file-finder
description: 指定された呼び出し箇所を検索して一覧にする
effort: low
tools: Read, Grep, Glob
---
ファイル名と行番号を返してください。変更はしません。

この例は.claude/agents/file-finder.mdへ置く定義の例です。lowを常に固定する強制設定ではありません。fork型への適用、モデルが対応しない段階、組織の上限は別に確認します。/tasksに表示された定義の値と、Agentツールへ渡された値、制約を反映した実効値も同じものとして扱わないでください。

自分の環境で記録を取る例です。秘密を含まない練習用フォルダーに、調査対象のsample.pyだけを用意します。次は新たに試すためのコマンド例で、保存済み実験をそのまま再掲したものではありません。

調査用のsample.pyは次の内容にします。これはコードを読むための試料で、APIへ実際に接続するコードではありません。実行せず、未定義のapiと例外処理の有無を調べます。

def add(a, b):
    return a + b

def pay(amount):
    # TODO: error handling
    return api.charge(amount)

claude -p --model sonnet --verbose --output-format stream-json \
  "sample.pyだけを読み、low effortのサブエージェントにapi.chargeの呼出し箇所を探させ、high effortの別の担当に例外処理の有無を調べさせてください。変更や外部送信はしません。" \
  > effort-test.jsonl

ログのassistantメッセージからtype: "tool_use"、name: "Agent"を探し、input.effortと依頼先を照合します。保存済みの編集部ログでは、次の2つの指定を確認できました。これは入力の一部だけを示す抜粋です。

{"subagent_type":"Explore","effort":"low"}
{"subagent_type":"general-purpose","effort":"high"}

ログには資料の内容やパスが含まれるため、そのまま外へ共有しないでください。また、指定値が記録されたことから、品質が上がったことや費用が減ったことまでは分かりません。同じ課題で答えの網羅率、誤り、全試行の使用量を比較する必要があります。公式のstream-json出力例では--verboseを併用しています。

どの作業のeffortをlowにして、どれをhighにするか

公式資料によると、effortを下げると単純な作業が速く安く終わり、上げるとClaudeが複雑な問題をより深く考えます。これを踏まえた振り分けの例です（編集部の提案）。

モデルとの組み合わせも考えられます。探す係をHaiku 5.5のような小型モデルにし、確かめる係を上位のモデルにする方法です。モデルも、依頼文や定義ファイルで指定できます。v2.1.317からは、サブエージェントのモデルをメインの会話と変えると、effortを指定しない時の深さも変わることがあります（詳しくはよくある質問へ）。

effortを指定する前の注意点

• 版：v2.1.292以降が必要です。claude --versionで確かめます。
• デスクトップアプリ：Lydia Hallieは10月7日の続きの投稿で「デスクトップ対応はまもなく」と書いています。デスクトップアプリで使うときは、対応を確かめてから使います。
• 組織の上限：組織がeffortの上限を決めている場合、それより高い値は上限の値で実行されます。JSON形式の出力やバックグラウンドのエージェントでは、警告も出ません。この記事の実験では、組織の上限を設定した場合の挙動までは検証していません。
• 使用量：サブエージェントの依頼も、使用量に含まれます。highを多く使えば、そのぶん消費が増える可能性があります。

よくある質問

何も指定しないと、どの深さで動きますか？

v2.1.317からは、メインの会話と違うモデルのサブエージェントは、セッションのeffortを引き継ぎません。/effortや設定ファイルのmodelSettingsでそのモデルに段階を保存していれば、その段階で動きます。どこにも指定がなければ、そのモデルの初期値で動きます。agent teams（複数のClaude Codeを組ませて作業する機能）のチームメイトも同じです（公式の変更履歴）。編集部の確認では、メインの会話と同じモデルのサブエージェントはセッションのeffortのままでした（次の表）。

編集部は11月3日、メインの会話をSonnet 5.5と--effort highで動かし、effortを指定せずにHaikuとSonnetのサブエージェントを1体ずつ起動しました。次の表は、ツールの実行前に動くフックが受け取ったeffortの値を、条件ごとに1回ずつ記録した結果です。

メインの会話は、CLAUDE_CODE_EFFORT_LEVELの回だけlowで、ほかはhighでした。mediumは、公式のモデル設定にあるHaiku 5.5の初期値です。定義ファイルにmodel: haikuだけを書いたサブエージェントもmediumでした。Haikuにlowを設定したうえでCLAUDE_CODE_SUBAGENT_EFFORT=highを付けると、Haikuのサブエージェントはhighでした。

effortLevelとCLAUDE_CODE_EFFORT_LEVELの行は、セッションのeffortとは別の指定が効いた例です。公式の設定一覧によると、ユーザー設定ファイルのeffortLevelは、Opus 5.5とそれ以降のモデルには使われません。プロジェクト・ローカル・管理設定のものと--settingsで渡したものは、すべてのモデルに使われます。編集部のユーザー設定ファイルにはxhighが入っていましたが、条件が「v2.1.317」だけの行のHaikuはmediumで、この説明と合います。プロジェクトの設定ファイルでは試していません。CLAUDE_CODE_EFFORT_LEVELは、公式では依頼文や定義ファイルの指定より優先します。この組み合わせも試していません。

モデルは、model: haikuを定義ファイルに書いた回を除いて、Agentツールの呼び出しで指定しました。プロジェクトの設定を読み込んだのも、その回だけです。--settingsの回は/effortでの保存ではありません。確かめたのは記録された値だけで、考える量や質、費用の変化は測っていません。チームメイトの動きも試していません。

たとえば、メインの会話を--effort highで動かし、探す係のサブエージェントだけをHaikuにしているとします。Haikuに段階を保存しておらず、ほかの指定もなければ、この確認と同じ条件では、探す係はhighではなくmediumで動きます。深さを決めておきたい時に使えるのは、依頼文か定義ファイルでの明示と、CLAUDE_CODE_SUBAGENT_EFFORTです。11月3日の時点で、公式のモデル設定とサブエージェントのページには、この変更とCLAUDE_CODE_SUBAGENT_EFFORTの説明がまだありません。agent teamsのページも、チームメイトはチームを率いるリーダーの段階を引き継ぐという、以前の説明のままです。

日本語の依頼でも効きますか？

編集部は、日本語の依頼文に「low effort」「high effort」という語を入れて試し、値が渡ることを確かめました。記録は1回だけなので、別の言い回しでも同じように値が渡るかは、まだ確かめていません。

まとめ：作業ごとに、effortを分けて頼む

v2.1.292以降は、1回の依頼の中で「数をこなす係は軽く、確かめる係は深く」と、深さを分けて頼めます。まずは検索と確認が混ざった依頼を1つ選び、深さを書き分けて頼んでみてください。同じ役割を何度も使うなら、定義ファイルに書いて固定するのが次の一歩です。