投稿者 投稿日: カテゴリー Claude
サブエージェント別モデル指定とは、作業ごとに使うAIモデルを個別に割り当てる設定のことです。
商品CSVの整形やログの読み取りといった軽い作業まで最上位モデルで走らせていると、費用は用途に関係なく最上位の単価で積み上がります。Claude Codeでは、サブエージェント（特定の作業に特化した子エージェント）ごとにmodelフィールドでモデルを指定できます。定義ファイルに1行足すだけの設定です。本記事は、EC支援19年・5,000社超の実績を持ち、AI導入支援は2023年から提供する株式会社オルセル（うるチカラ運営）の現場知見にもとづき、EC運営の実務で使うサブエージェントの構成と、モデル指定の優先順位を整理します。
読み終えたあとに手を動かす順序を先に示します。まず自社の作業を「読むだけ」「書き換える」「設計する」の3層に分け、次に各層へモデルを割り当て、最後に.claude/agents/配下に定義ファイルを置きます。ここまでで30分から1時間です。
モデル指定の仕組みと優先順位
結論として、モデルの決まり方には4段階の優先順位があります。この順序を知らないまま設定すると、定義ファイルに書いたのに反映されないという事態になります。
Claude Code公式ドキュメントによると、サブエージェントは.claude/agents/または~/.claude/agents/配下のMarkdownファイルで定義します。ファイル冒頭のYAMLフロントマターに設定を書き、本文がそのサブエージェントのシステムプロンプトになります。必須項目はnameとdescriptionの2つだけで、それ以外は省略可能です。
modelフィールドに指定できる値は、エイリアスのsonnet、opus、haiku、fable、完全なモデルID（claude-opus-5やclaude-sonnet-5など）、そしてinheritです。省略した場合はinheritとして扱われ、メインの会話と同じモデルが使われます。ここが費用面の落とし穴で、何も書かなければ最上位モデルで会話している間はサブエージェントも最上位で動きます。
優先順位は次の順序です。第1に環境変数CLAUDE_CODE_SUBAGENT_MODEL、第2に呼び出しごとに渡されるmodelパラメータ、第3に定義ファイルのmodelフロントマター、第4にメイン会話のモデルです。環境変数が最も強いため、組織で一律に安いモデルへ寄せたい場合はここを使います。逆に、定義ファイルに書いたモデルが効かないと感じたら、環境変数が設定されていないかを確認してください。バージョン2.1.196以降は、環境変数にinheritを設定した場合は未設定と同じ扱いになり、以降の優先順位へ処理が進みます。
組織のavailableModels許可リストで使えるモデルを制限している場合、除外されたモデルを指定した値はスキップされ、継承したモデルで動きます。企業として使えるモデルを絞っている環境では、まず許可リストの内容を確認する必要があります。
定義ファイル以外の指定方法もあります。Claude Codeの起動時に--agentsフラグでJSONを渡すと、そのセッション限りのサブエージェントを定義できます。ディスクには保存されないため、試したい構成を短時間で検証する用途に向きます。JSONで指定できる項目はファイル定義と同じで、description、prompt、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、skills、initialPrompt、memory、effort、background、isolation、colorが使えます。ファイル定義の本文に相当するシステムプロンプトはpromptとして渡します。まず--agentsで当たりを付けてから、確定したものをファイルへ落とす進め方が手戻りが少ないやり方です。
なお組織で共通化したい場合は、管理者が配布する管理サブエージェントという仕組みもあります。管理設定のディレクトリ内の.claude/agents/にファイルを置くと、同名のプロジェクト定義やユーザー定義より優先されます。複数店舗を運営していて、担当者ごとに設定がばらつく状況なら、この仕組みで下限を揃えるという選択肢が取れます。
思考量の設定も指定できます。effortフィールドでlow、medium、high、xhigh、maxのいずれかを選び、セッション全体の設定を上書きします。使える段階はモデルによって異なります。モデルの選択と思考量の選択は別軸なので、「安いモデルで思考量を上げる」「上位モデルで思考量を下げる」という組み合わせが可能です。費用と品質の調整幅は、この2軸で考えると広がります。思考量とコストの関係はOpus 5の思考量とコスト最適化で整理した内容がそのまま当てはまります。
EC運営の作業を3層に分けて割り当てる
先に割り当ての方針を書きます。読むだけの作業は軽いモデル、書き換える作業は中位モデル、設計と判断を含む作業は上位モデルです。この3層で分けると、8割の作業が上位モデルを必要としないことが見えてきます。
第1層は「読むだけ」の作業です。商品CSVの列構成を確認する、エラーログから該当箇所を探す、既存の商品説明文から特定の表記を洗い出す、ファイル構成を把握するといった処理が入ります。判断の余地が小さく、正解が明確な作業です。ここはhaikuで十分な場面が多く見られます。処理件数が多いのもこの層なので、単価差の効果が最も大きく出ます。
第2層は「書き換える」作業です。商品名の表記統一、CSVの形式変換、既存コードの軽微な修正、テストの追加が該当します。事実の取り扱いに正確さが必要ですが、設計判断はありません。sonnetが適する層です。
第3層は「設計する」作業です。複数モールへの同時出品を前提としたデータ構造の設計、在庫連携の仕組みの検討、障害発生時の原因切り分け、レビューでの品質判断が入ります。ここは上位モデルを使う価値があります。件数が少ないため、単価が高くても総額への影響は限定的です。
この分け方には根拠があります。Cursorのエージェント群を使った検証では、上位モデルが作業を計画し、実際のコーディングは安価なモデルが担当する構成で大部分をこなせるという結果が報告されています。詳細はエージェント群でのモデル分担で扱いました。計画と実行を分け、実行側を安いモデルに寄せる発想は、Claude Codeのサブエージェント設計にもそのまま使えます。
割り当ての目安として、EC運営の開発作業で発生する件数の比率を挙げます。店舗運営の現場感覚では、読むだけの作業が全体の5割前後、書き換えが3割前後、設計が2割前後です。ジャンルや開発体制で変わるため概算ですが、件数の多い層を安いモデルへ寄せる効果が大きいことは構造として言えます。
具体的な業務に落とすと、この3層は次のように並びます。第1層に置きやすいのは、楽天RMSからダウンロードした商品CSVの列確認、Amazonのフラットファイルでエラーになった行の抽出、注文データの件数照合、既存の商品説明文から禁止表現を洗い出す作業です。いずれも読んで数えるだけで、判断が入りません。第2層は、商品名の全角半角の統一、単位表記の統一、モール間のCSV列名のマッピング、画像ファイル名の一括変換といった書き換え作業です。第3層は、SKU設計の変更、在庫を複数モールでどう按分するかの方針決定、受注取込が二重に走った場合の復旧手順の検討が入ります。第3層の作業は月に数回しか発生しないのが普通で、そこに上位モデルを使っても総額は動きません。
この分類を最初に紙に書き出すことをおすすめします。5,000社支援の中で何度も再現したパターンとして、分類せずにモデルを割り当てようとすると「とりあえず全部上位モデル」に落ち着きます。逆に作業名を20個ほど並べて層を振ると、8割が第1層と第2層に入ることが見えて、割り当ての判断が自然に決まります。
もう一点、サブエージェントは既定で背景実行になります。バージョン2.1.198以降、Claudeが必要と判断しない限りサブエージェントは背景タスクとして動きます。背景実行のサブエージェントは使える組み込みツールが絞られ、Read、Grep、Glob、Bash、Edit、Write、WebFetch、WebSearchなどに限定されます。定義ファイルのtools欄に書いたツールでも、背景実行では外れることがあります。同じ定義が前景と背景で違うツール構成になる点は、動作確認時に押さえておくべき挙動です。
定義ファイル3本と検証プロンプト2本
ここから実装に入ります。以下にコードブロックを5本置きます。サブエージェントの定義例が3本、検証用のプロンプトが2本です。定義ファイルは.claude/agents/配下に、ファイル名を任意で保存します。識別はnameフィールドで行うため、ファイル名と一致させる必要はありません。
（用途：読むだけの調査用サブエージェント）
---
name: ec-data-inspector
description: 商品CSVやログを読んで事実を報告する調査担当。書き換えは行わない。
tools: Read, Grep, Glob
model: haiku
effort: low
color: blue
---
あなたはECサイトのデータ調査担当です。渡されたファイルを読み、事実だけを報告します。
守ること:
1. ファイルの書き換えを提案しない。報告だけを行う
2. 件数・列名・値の分布を数字で示す
3. 推測を述べる場合は「推測」と明記する
4. 報告は箇条書きで10行以内にまとめる
報告に必ず含める項目:
- 対象ファイル名と行数
- 列名の一覧
- 空欄がある列と件数
- 表記が揺れている値の例（最大5件）
（用途：書き換え専用のサブエージェント）
---
name: ec-csv-normalizer
description: 商品CSVの表記統一と形式変換を行う。設計変更は行わない。
tools: Read, Write, Edit, Bash
model: sonnet
effort: medium
color: green
---
あなたはECの商品データを整形する担当です。指示された範囲だけを書き換えます。
守ること:
1. 指示されていない列を変更しない
2. 元ファイルは必ず別名で残し、上書きしない
3. 文字コードは指定がなければUTF-8で保存する
4. 変更した件数を最後に報告する
表記統一のルール:
- 全角英数は半角に統一する
- 単位は「g」「ml」「cm」に統一する
- 商品名の連続スペースは1つにまとめる
- 環境依存文字は使用しない
（用途：設計とレビューを担う上位モデルのサブエージェント）
---
name: ec-architecture-reviewer
description: 複数モール連携やデータ構造の設計判断、実装のレビューを担当する。
tools: Read, Grep, Glob, Bash, WebFetch
model: claude-opus-5
effort: high
color: purple
---
あなたはEC基盤の設計レビュー担当です。実装の前提と影響範囲を検討します。
検討する観点:
1. 楽天・Amazon・Yahoo!ショッピングの仕様差がデータ構造に与える影響
2. 在庫と受注のデータが二重更新される可能性
3. 障害時に売上へ直接影響する箇所の特定
4. 変更を戻せるか（ロールバックの手順があるか）
出力の形式:
- 結論を先に1文
- 懸念点を影響の大きい順に3つまで
- 各懸念に対する具体的な確認方法
- 判断を保留すべき点があれば「要確認」と明記
（用途：現在の設定がどう解決されるか検証する）
プロンプト4：モデル指定の解決結果を確認する
あなたはClaude Codeの設定を点検するアシスタントです。
以下の情報から、各サブエージェントが実際にどのモデルで動くかを判定してください。
判定の優先順位:
1. 環境変数 CLAUDE_CODE_SUBAGENT_MODEL
2. 呼び出しごとの model パラメータ
3. 定義ファイルの model フロントマター
4. メイン会話のモデル
前提情報:
- 環境変数の設定値: {未設定 / 値}
- メイン会話のモデル: {値}
- 各サブエージェントの定義（name と model のみ）: {一覧を貼る}
- 組織の availableModels 許可リスト: {未設定 / 一覧}
出力:
- サブエージェント名 / 実際に使われるモデル / 根拠となった優先順位の番号
- 意図と食い違っている箇所があれば、修正すべき設定を1行で
（用途：作業を3層に分類して割り当てを決める）
プロンプト5：EC開発の作業を3層に分けてモデルを割り当てる
あなたはEC事業者の開発体制を設計するテクニカルディレクターです。
以下の作業リストを3層に分類し、モデルの割り当て案を作ってください。
分類の基準:
- 第1層（読むだけ）判断の余地が小さく、正解が明確
- 第2層（書き換える）正確さが必要だが設計判断はない
- 第3層（設計する）影響範囲の判断や仕様の検討を含む
作業リスト:
{商品CSVの確認、表記統一、ログ調査、在庫連携の設計、レビュー対応の文面作成、テスト追加 など}
出力する項目:
1. 作業ごとの層（1 / 2 / 3）と理由（1行）
2. 推奨モデル（haiku / sonnet / opus / fable のいずれか）
3. 推奨する effort（low / medium / high / xhigh / max）
4. 月あたりの想定実行回数
5. 最後に「最も費用削減効果が大きい作業」を3つ
つまずきやすい4つのパターン
1つ目は、定義ファイルにモデルを書いたのに反映されないパターンです。環境変数CLAUDE_CODE_SUBAGENT_MODELが設定されていると、そちらが優先されます。共有環境やCI（継続的インテグレーション）の設定で環境変数が入っていることに気付かず、原因を探して時間を使うケースが起きます。プロンプト4のような確認手順を1度通しておくと切り分けが早くなります。
2つ目は、安いモデルへ寄せすぎて手戻りが増えるパターンです。判断を含む作業を軽いモデルに任せると、成果物の修正に人の時間がかかります。単価の差より人件費のほうが高いため、総コストで悪化します。判断の余地がある作業は、安易に下げない線引きが要ります。
3つ目は、ツール制限を忘れるパターンです。調査用のサブエージェントにWriteやEditを残しておくと、報告だけを頼んだのにファイルを書き換えることがあります。tools欄で読み取り系だけを許可するか、disallowedToolsで書き込み系を外してください。両方を指定した場合はdisallowedToolsが先に適用され、その残りに対してtoolsが解決されます。
4つ目は、nameの重複です。同じディレクトリ配下で同名のサブエージェントが2つあると、片方だけが読み込まれ、どちらが有効かはファイルの読み取り順で決まります。/doctorの点検で重複が報告されるため、定義を増やしたら一度通しておくと安全です。命名は「ec-」のような接頭辞を付けると衝突しにくくなります。
費用と工数の目安
初期設定にかかる時間は、作業の分類に30分、定義ファイル3本の作成に30分から1時間です。既に開発作業をClaude Codeで回している環境なら、半日以内で移行できます。
費用の削減幅は、作業構成に依存します。読むだけの作業が全体の5割を占め、その層を上位モデルから軽いモデルへ移した場合、その5割分の単価が下がる計算です。実際の削減率はトークン量の分布で変わるため、断定はできません。判断材料として、切り替え前の1か月と切り替え後の1か月で請求額を比べる運用にしてください。月額プランはClaude Proが20米ドル、上位にMaxプランがある構成で、API経由の従量課金と併用するケースもあります。
測り方も決めておく必要があります。おすすめは、代表的な作業を5つ選び、それぞれ10回分の実行にかかったトークン量と所要時間を記録する方法です。列は「作業名、モデル、実行回数、入力トークン、出力トークン、人が修正した箇所の数、所要時間」の7つで足ります。2週間分たまれば、どの層でモデルを下げても問題ないかが数字で判断できます。感覚で「安いモデルでも十分だった」と決めると、あとで品質の低下に気付いても原因を特定できません。
削減効果を測るときの注意点として、手戻り時間も計上してください。モデルを下げた結果、修正のやり取りが増えていれば、金額の削減と時間の増加を差し引きで見る必要があります。担当者の時間単価を仮に3,000円とすると、月に3時間の手戻り増加は9,000円相当です。API費用の削減がそれを下回るなら、下げすぎと判断できます。
半年先を見た設計の考え方
サブエージェント別のモデル指定は、AIの使い方が「1つの賢いモデルに全部頼む」から「役割ごとに適切なモデルを配置する」へ移る流れの一部だと見ています。人の組織で、調査は担当者、設計は責任者が行うのと同じ構造です。この構造で設計しておくと、新しいモデルが出たときの入れ替えが1行の変更で済みます。
EC事業者にとって実利が大きいのは、担当者の交代に強くなる点です。サブエージェントの定義ファイルには、守るべきルールと出力形式が書かれています。これは業務手順書と同じ機能を持ちます。人が入れ替わっても、定義ファイルが残っていれば作業の品質が保たれます。属人化の解消という観点で、コスト削減以上の価値がある部分です。
もう一つの論点は、権限設計との組み合わせです。permissionModeで権限の扱いを、toolsで使えるツールを制限できるため、「調査だけのエージェントには書き込みを許さない」という設計をファイル単位で表現できます。受注データや決済に関わる処理を扱うなら、モデルの選択と同じ重みで権限の線引きを決める必要があります。業務別のモデル選択の全体像はClaudeモデルの選び方で整理した4クラスの枠組みが使えます。
よくある質問
モデルを指定しないとどうなりますか
inheritとして扱われ、メインの会話と同じモデルで動きます。上位モデルで会話している間は、軽い調査作業も上位モデルの単価で処理されます。費用を抑えたいなら、明示的に指定してください。
定義ファイルを書き換えたら再起動が必要ですか
いいえ、通常は不要です。Claude Codeは~/.claude/agents/と.claude/agents/を監視しており、数秒以内に変更を検知します。ただし、そのスコープで最初のエージェントファイルを新しいディレクトリに作った場合は再起動が必要です。
完全なモデルIDとエイリアスはどちらを使うべきですか
運用の安定を重視するなら完全なモデルIDです。claude-opus-5のように指定すると、モデルが更新されても挙動が変わりません。エイリアスのopusは最新のものを指すため、意図せず挙動が変わる可能性があります。検証環境ではエイリアス、本番ではIDという使い分けもできます。
サブエージェントは何個まで作るべきですか
役割が明確に分かれる単位で3〜5個から始めるのが扱いやすい規模です。増やしすぎると、どのエージェントに任せるべきかの判断自体が煩雑になります。description欄に「いつ使うか」を具体的に書いておくと、選択が安定します。
思考量の設定はモデル選択と何が違いますか
モデル選択は使うAIそのものの選択で、思考量は回答前に考える量の設定です。別軸なので、軽いモデルで思考量を上げる、上位モデルで思考量を下げる、といった組み合わせができます。使える段階はモデルによって異なります。
組織で使えるモデルが制限されている場合はどうなりますか
許可リストに含まれないモデルを指定した値はスキップされ、継承したモデルで動きます。エラーにはならないため、意図した設定が無視されていることに気付きにくい挙動です。設定の前に許可リストの内容を確認してください。
著者：齋藤竹紘（株式会社オルセル 編集長／5,000社以上のEC支援実績／書籍3冊）
参考文献
- Claude Code Docs｜Create custom subagents
- Claude Code Docs｜Model configuration
- Claude Platform Docs｜Models overview
- Anthropic｜Claude Code
※うるチカラでは、生成AIの導入支援から運用最適化まで、貴社のEC事業に合わせたカスタマイズ提案を行っています。無料相談（30分）も実施中ですので、お気軽にお問い合わせください。
https://uruchikara.jp/contact/
【監修】齋藤竹紘（株式会社オルセル代表 / 19年・5,000社のEC支援実績）
株式会社オルセル代表取締役 / うるチカラ編集長。19年・5,000社以上のEC支援実績を持ち、楽天市場・Amazon・Yahoo!ショッピング・Shopify・Shopee越境ECの実装ノウハウを保有。AI×ECに関する書籍を3冊執筆。「現場で使えるAI実装」を一次情報として発信しています。
この記事を読んだ人は、こんな記事も読んでいます
