メインコンテンツへスキップ
見出し画像

Claude Codeサブエージェント、使う場面と軽くする設定

    結論:サブエージェントは「ログや検索結果が大量に出る、独立した作業」に絞って使い、軽い作業はHaikuと低いeffortに、レビュー役は読み取り専用にするのが公式ドキュメントに沿ったやり方です。

    サブエージェントの処理も本体と同じ利用枠を消費するので、「分ければ節約になる」わけではありません。

    この記事は2026年11月4日夜(日本時間)時点のClaude Code公式ドキュメントと変更履歴をまとめたもので、筆者が実機で計測・検証したものではありません。

    そもそも何が「軽く」なるのか

    サブエージェントは、本体(メインの会話)とは別のコンテキストで動き、結果の要約だけを本体に返します。軽くなるのは本体のコンテキストで、利用量ではありません。公式ドキュメントには、サブエージェント自身のリクエストもメインの会話と同じ利用枠(usage limits)にカウントされると書かれています。

    プランごとの利用枠については、11月3日朝の記事で整理しています。

    ChatGPTとCodexの利用枠が12月から共通に、Claudeは最上位プランの5時間制限を撤廃:AIコーディングのサブスクを見直す前に確認したいこと

    使う場面・使わない場面

    公式ドキュメントの「Choose between subagents and main conversation」の判断基準は次のとおりです。

    メインの会話でやる

    • やり取りを何度も重ねて詰めていく作業

    • 計画→実装→テストのように、前の工程の情報を引き継ぐ作業

    • すぐ終わる小さな修正

    • 待ち時間を短くしたいとき(サブエージェントはゼロから情報を集め直すため)

    サブエージェントに任せる

    • テスト実行、ドキュメント取得、ログ解析など、出力が多くて本体に残したくない作業

    • 使えるツールや権限を制限したい作業

    • 単独で完結し、要約を返せば済む作業

    同じ手順を何度も使い回したいだけなら、本体の会話の中で動く「スキル」が向いているとも書かれています。今の会話について横からちょっと質問したいときは /btw を使います。

    設定1:軽い作業はHaikuで動かす

    サブエージェントは .claude/agents/(プロジェクト用)か ~/.claude/agents/(全プロジェクト共通)にMarkdownで定義し、frontmatterの model でモデルを決めます。料金の公式ページも「単純なサブエージェントには model: haiku を指定する」よう勧めています。

    モデルは次の順で決まります。

    • 1. 呼び出し時にClaudeが渡す model 指定

    • 2. 定義ファイルの model(inherit は本体と同じモデル)

    • 3. 環境変数 CLAUDE_CODE_SUBAGENT_MODEL

    • 4. 本体のモデル

    つまずきやすい点:CLAUDE_CODE_SUBAGENT_MODEL は既定値の扱いなので、これだけを設定しても、定義ファイルの指定が優先されます。また、組み込みのExploreとPlanのモデルも変わりません。すべてのサブエージェントを1つのモデルに固定したい場合は、settings.jsonの env に CLAUDE_CODE_SUBAGENT_MODEL と CLAUDE_CODE_SUBAGENT_MODEL_FORCE: "1" を両方書きます(v2.1.257以降)。コード探索だけ安いモデルにしたい場合は、Explore という名前で model: haiku を指定したサブエージェントを自分で定義すると、組み込みのExploreを上書きできます。

    どのモデルで動いているかは /tasks で確認できます(v2.1.242以降)。

    設定2:effort(考える量)も分ける

    frontmatterの effort には low〜max を指定でき、セッション全体のeffort設定より優先されます。ただし、環境変数 CLAUDE_CODE_EFFORT_LEVEL を設定するとそちらが優先されます。

    最近の変更点

    • v2.1.316:何も指定がないときのサブエージェントのeffortを決める環境変数 CLAUDE_CODE_SUBAGENT_EFFORT が追加された(変更履歴より。筆者確認時点では環境変数一覧のページには載っていない)

    • v2.1.317:本体と違うモデルで動くサブエージェントは、セッションのeffortではなく、そのモデルに保存された設定か既定値を使うようになった

    本体をOpus・高effortで使っていても、Haikuのサブエージェントには本体のeffortが引き継がれません。effortを固定したいなら effort を書いておくのが確実です。

    設定3:レビュー役は読み取り専用に

    tools を許可リスト、disallowedTools を禁止リストとして使えます。

    • tools: Read, Grep, Glob:ファイルを読むことしかできないレビュー役になる

    • disallowedTools: mcp__github:GitHubのMCPサーバーのツールだけを外す

    つまずきやすい点:disallowedTools に Bash(git push *) と書くと、git pushだけでなくBashツールがまるごと使えなくなります。Bashは残して特定のコマンドだけ禁止したい場合は、settingsの permissions.deny に Bash(git push *) を書きます(このルールは本体にも適用されます)。

    エージェントに渡す権限の絞り方は、今朝の記事でも扱いました。

    AIエージェント専用GitHubアカウントの作り方と権限設定

    設定4:増やしすぎない

    自作サブエージェントの説明文(description)は、合計で15,000トークンを超えると起動時に警告が出ます。説明文は短くし、詳しい指示は本文(そのサブエージェントが動くときだけ読み込まれる)に書きます。

    Anthropicは2026年10月22日付の記事で、Claude Platformでエージェントを作る人に向けて、多くのサブエージェントは「スキル+ツール」として本体に統合したほうが品質・コスト・待ち時間の面で有利なことが多いと述べています。サブエージェントを残す条件は次の3つです。

    • コンテキストが膨らんで、目に見えて性能が落ちる

    • 並列で進め、終わったら捨ててよい作業がある

    • ツール選びに迷う、または指示がぶつかる

    これはAPIでエージェントを作る人向けの話ですが、Claude Codeで自作のサブエージェントを見直すときの基準としても使えると筆者は考えています。

    今日やること

    • 1. .claude/agents/ を開き、上の3条件に当てはまらないサブエージェントはスキルにできないか検討する

    • 2. 調査・ログ解析用のサブエージェントに model: haiku と effort を書く

    • 3. レビュー役は tools: Read, Grep, Glob にする

    • 4. /tasks でモデルとeffortを確認する

    • 5. /usage の内訳で、サブエージェントが利用量の何割を占めているかを見る(Pro・Maxなどのプラン)

    実際にどれだけ節約できるかは、作業の内容によって変わります。数字は必ず自分の環境で確かめてください。

    参考リンク

    この記事が参加している募集

     
     
    Claude Code・Codex・GeminiなどのAIエージェントを、開発の実務でどう使うかを書いています。設定手順、ツールの比較、ハマりどころを毎朝更新。エンジニアの仕事と働き方の話もときどき。

    あなたへのおすすめ