Claude Codeサブエージェントのモデル配分設計 — 役割ごとにOpus/Sonnet/Haikuを割り当てる
サブエージェントを全部同じモデルで動かすとコストと精度が釣り合わない。公式ドキュメントのmodelフィールドと料金表から、役割別の割り当て原則を導く。
なぜ全サブエージェントを同じモデルで動かすと損をするのか
サブエージェントは呼び出すたびに新しいコンテキストウィンドウを持つ独立したエージェントです。既定では呼び出し元の会話と同じモデルを引き継ぎます。何も設定しなければ、コードを探索するだけの軽い調査タスクも、最終成果物の品質を判定するタスクも、同じモデルで動きます。
Claude Codeのコスト削減ガイドはこの点について具体的な指針を示しています。「Sonnetはほとんどのコーディング作業をうまくこなし、Opusより安い。Opusは複雑なアーキテクチャ判断や多段階の推論に取っておく」としたうえで、「単純なサブエージェントのタスクには、サブエージェント設定でmodel: haikuを指定する」ことを推奨しています。モデルはmodelフィールド1つで役割ごとに変えられます。変えない構成のままだと、単純作業に高いモデルの単価を払い続けるか、判断が必要な作業を安いモデルに任せて精度を落とすか、どちらかに寄ります。
サブエージェントのmodelフィールドが決める割り当ての仕組み
サブエージェント定義のmodelフィールドには、sonnet / opus / haiku / fableのエイリアス、claude-opus-5のようなフルのモデルID、または呼び出し元の会話と同じモデルを使うinheritを指定できます。Claude Codeはサブエージェントを起動するとき、次の順でモデルを解決します。
- Claudeがサブエージェントを呼び出す際に個別に渡す
modelパラメータ - サブエージェント定義の
modelフロントマター(inheritならここで会話のモデルが選ばれる) CLAUDE_CODE_SUBAGENT_MODEL環境変数(エイリアスかモデルIDを設定した場合)- 会話のモデルそのもの(何も指定がない場合の最終フォールバック)
ただしCLAUDE_CODE_SUBAGENT_MODELを設定しただけでは、組み込みのExplore・Planのモデルは変わりません。この2つを変えるには後述のCLAUDE_CODE_SUBAGENT_MODEL_FORCEが必要です。
組織のavailableModels許可リストで特定のモデルが禁止されている場合は、この解決結果がさらに置き換わります。エイリアス指定(opusなど)が禁止されていれば許可リスト内で最新のバージョンに、それ以外の値が禁止されていれば会話のモデルに差し替わります。インタラクティブセッションでは、どちらのモデルへ差し替えたかが警告として表示されます。
コンテキストが分離されることもモデル選びに影響する
サブエージェントは新しく起動するたびに、会話履歴もこれまで読んだファイルも引き継がない、まっさらなコンテキストウィンドウから始まります。呼び出し元のClaudeが依頼内容を要約した委任メッセージを組み立て、サブエージェントはその要約だけを頼りに作業します。例外は現在の会話をまるごと引き継ぐフォークで、これは通常のサブエージェントと違いモデルも呼び出し元と同じものを使います。
この仕組みは、モデルの選び方にもう1つの制約を加えます。通常のサブエージェントは会話の文脈を持たないぶん、委任メッセージの意図を正しく汲み取る力がそのまま結果の質を左右します。曖昧さを含む依頼(「よしなに直しておいて」に近い粒度の指示)を低コストなモデルに渡すと、文脈が無い状態で誤読するリスクが会話のモデルより上がります。指示が具体的で完結しているタスク(特定のログを検索する、決まったフォーマットで抽出する)ほど低コストなモデルへ安心して渡せます。この線引きは、価格だけでなくコンテキスト分離の性質からも導けます。
Claude Code自身の組み込みサブエージェントも役割で分けている
役割ごとにモデルを変えるという発想は、Claude Codeが自分の組み込みサブエージェントですでに実践している設計です。公式ドキュメントが挙げる組み込みサブエージェントのモデル割り当てを並べると、役割の重さと単価の対応がはっきり見えます。
| 組み込みサブエージェント | モデルの扱い | 役割 |
|---|---|---|
| Explore | モデルの扱い会話のモデルを継承(Claude API利用時はOpusを上限にキャップ) | 役割コード検索・調査専用の読み取り専用エージェント |
| Plan | モデルの扱い会話のモデルを継承 | 役割Planモードで実装前にコードベースを調べる調査エージェント |
| general-purpose | モデルの扱いモデル解決順に従う(通常は会話のモデル) | 役割探索と変更の両方が要る複雑な多段階タスク |
| claude(汎用) | モデルの扱い固有のモデル指定なし。呼び出し時のモデル解決順に従う | 役割専用エージェントに当てはまらないタスク全般のキャッチオール |
| statusline-setup | モデルの扱いSonnetに固定 | 役割/statuslineでステータスラインを設定するとき |
| claude-code-guide | モデルの扱いHaikuに固定 | 役割Claude Codeの機能について質問されたとき |
ここで注目すべきは、claude-code-guide(製品の使い方に関する質問応答)とstatusline-setup(設定ファイルを組み立てる定型タスク)には、会話のモデルに関係なく固定でHaikuとSonnetが割り当てられている点です。どちらも「求められる判断の幅が最初から決まっているタスク」で、会話がOpusで進んでいても、この2つまで高いモデルへ引き上げる必要はありません。一方、ExploreとPlanのような調査系は会話のモデルを継承します。Explore側はOpusを上限にキャップしているため、会話がFable 5.1で進んでいても、Exploreまでその単価で動くことはありません。
ユーザー定義のサブエージェントでも同じ考え方が使えます。Exploreという名前でユーザー・プロジェクトのサブエージェントを定義すれば組み込みのExploreを上書きでき、model: haikuと明示すれば調査を常に低コストなモデルへ固定できます。
Opus/Sonnet/Haikuの価格差を役割にどう対応させるか
公式の料金表を並べると、モデル間の単価差は次のとおりになります。
| モデル | 入力 / 出力(100万トークンあたり) | 既定effort | コンテキストウィンドウ |
|---|---|---|---|
| Claude Opus 5 | 入力 / 出力(100万トークンあたり)$5 / $25 | 既定efforthigh | コンテキストウィンドウ100万トークン |
| Claude Sonnet 5 | 入力 / 出力(100万トークンあたり)$2 / $10 | 既定efforthigh | コンテキストウィンドウ100万トークン |
| Claude Haiku 4.5 | 入力 / 出力(100万トークンあたり)$1 / $5 | 既定effort非対応 | コンテキストウィンドウ20万トークン |
| Claude Fable 5.1 | 入力 / 出力(100万トークンあたり)$10 / $50 | 既定efforthigh(常時アダプティブ思考) | コンテキストウィンドウ100万トークン |
Opusの出力単価はHaikuの5倍、Fableは10倍にあたります。サブエージェントを並列で何本も走らせる構成では、この単価差が呼び出し回数の分だけ積み上がります。だからこそ公式ガイドは「単純作業はHaiku」と割り切った指針を出しています。ただしHaikuはコンテキストウィンドウが20万トークンとほかの現行モデルの5分の1しかない点には注意が要ります。大きなログファイルや長いソースツリーを丸ごと読ませるサブエージェントにHaikuを割り当てると、単価では得をしても、コンテキストが足りず処理を最後まで終えられないことがあります。表のとおりHaikuはeffortにも非対応なので、後述するeffortによる代替も使えません。
Fable 5.1は常時アダプティブ思考が入り、要求される推論の深さが他モデルより一段重くなります。単価も最も高いため、大量に並列起動するfan-out型のサブエージェントではなく、長時間・高難度の推論をこなす少数のサブエージェントに絞って使うのが料金表の裏づけと整合します。
品質ゲートと調査タスクで割り当てを変える設計原則
ここまでの事実を組み合わせると、役割ごとに割り当てを変える原則が見えてきます。
- 判断や最終チェックを担うサブエージェント(レビュー・採点・統合): 誤りの見落としがそのまま成果物の品質に直結するため、
model: opusのように上位モデルへ固定するか、inheritで会話のモデルをそのまま使います。判断の重いタスクには単価より正確さを優先する構成です - 調査・下読み・単純な抽出を担うサブエージェント:
claude-code-guideと同じ考え方で、model: haikuかmodel: sonnetに軽くします。ただし対象がHaikuの20万トークン枠に収まるかは事前に確認します - 並列で多数起動するfan-outタスク: 1本あたりの単価が呼び出し数倍になる構成なので、Opus・Fableは避け、Sonnet以下に寄せます
effortフィールドを使えば、モデルを変えずに同じ効果を部分的に得ることもできます。サブエージェント定義にeffort: lowのように指定すると、そのサブエージェントだけ会話全体のeffortレベルを上書きできます。ただしこの代替はモデルによって対応状況が違い、Haiku 4.5はeffortに非対応です。Haikuを割り当てたサブエージェントでは、この代替案自体が使えません。単純作業をモデルごと下げるか、モデルは据え置いてeffortだけ下げるかは、対象タスクがモデルの知識差よりも思考量の差で困っているかどうかで選び分けます。
すべてのサブエージェントを一律に会話のモデルへ委ねるinherit一辺倒の構成では、判断の重さが違う役割に同じ単価を払い続けるか、逆に判断が要る役割まで安いモデルに落として精度を犠牲にするか、どちらかが起きやすくなります。inheritのままだと、単純作業にも会話と同じ単価がかかります。
意図しない格上げ・格下げを防ぐ確認ポイント
役割ごとにmodelを書き分けても、環境変数CLAUDE_CODE_SUBAGENT_MODEL_FORCEを1に設定していると、Explore・Planを含むすべてのサブエージェントのmodelフロントマターが無視され、強制的に1つのモデルへ統一されます(CLAUDE_CODE_SUBAGENT_MODEL_FORCEはClaude Code v2.1.257以降が必要)。個別に設計した役割別の割り当てごと上書きしてしまうため、設定した記憶がないまま有効になっていると「なぜmodel: opusと書いたサブエージェントがHaikuで動くのか」といった原因不明の挙動に見えます。
同様に、組織の許可リストでモデルがブロックされているケースも見た目上は同じ症状になります。/tasksを実行すると、いま動いているサブエージェントがどのモデル(と設定されていればeffortレベル)で動作しているかを行ごとに確認できるので、割り当てが意図通りかはここで裏を取れます。
/tasksまとめ
サブエージェントのモデル配分は、modelフィールド1つで役割ごとに変えられる設計対象です。Claude Code自身がclaude-code-guideをHaikuに固定しているように、調査や下読みのような軽い役割は低コストなモデルに寄せ、判断が重い役割は上位モデルに固定します。並列で多数起動するfan-out構成ほど、単価の低いモデルを選びます。CLAUDE_CODE_SUBAGENT_MODEL_FORCEのような全体強制の設定が入っていないかも合わせて確認すれば、設計した配分がそのまま反映されます。
割り当てを決める順番としては、まず品質ゲートに当たる役割を先に固定し、残りを安いモデルへ倒していく方法があります。逆に「まずHaikuで揃えて、精度が足りない役割だけ引き上げる」という順番だと、精度不足に気づくまでの間、判断の重いタスクが安いモデルで動き続けます。最終出力の正しさに直結する役割から上位モデルを割り当て、そこから外れる役割を段階的に下げていく方が、途中の状態でも致命的な誤りを抱えにくくなります。
サブエージェントの切り方そのものの設計はClaude Code Sub-agents完全ガイドに、モデル自体の使い分けの一般論はClaudeモデル比較に、全サブエージェントを一律で固定する環境変数の詳細はCLAUDE_CODE_SUBAGENT_MODELとはにまとめてあります。役割を先に切り、それぞれの役割にどのモデルを載せるかを後から決める、という順番を守れば、サブエージェントを増やすたびのモデル選びが単純になります。