Claude Codeサブエージェントの使い方｜実測で見る委任とコンテキスト節約

Claude Codeのサブエージェントとは、メインの会話とは別のコンテキスト（作業用の記憶領域）で動き、結果だけを返してくれる専門の作業役です。 たくさんのファイルを読む調査や、ログの読み込みのように「途中経過は多いが、欲しいのは結論だけ」という作業を任せると、メインの会話をすっきり保てます。

この記事では、Claude Code v2.1.283 で、12ファイル・約97KBの小さなサンプルリポジトリを使って実測しました。メインが自分でファイルを読んだ場合と、サブエージェントに任せた場合で、メインのコンテキストがどれだけ増えたか、descriptionの書き方で自動委任されるかどうか、4つのExploreを並列で動かした結果を数字で紹介します。frontmatterの項目は公式ドキュメント（code.claude.com/docs）の最新版で確認しています。

Claude Codeサブエージェントの早見表

.claude/agents/<名前>.md の先頭（frontmatter）に書ける項目の一覧です。必須は name と description の2つだけで、残りは必要に応じて足します。

本文（frontmatterの下）はそのエージェント専用のシステムプロンプトになります。本文はエージェントが動くときにだけ読み込まれるので、細かい手順はdescriptionではなく本文に書くのがコツです。

サブエージェントのしくみ

サブエージェントは、メインから「依頼文」を受け取り、自分専用のコンテキストでファイルを読んだりコマンドを実行したりして、最後の回答だけをメインに返します。

flowchart LR
    U[あなた] --> M[メインの会話]
    M -- 依頼文 --> S[サブエージェント<br>別のコンテキスト]
    S -- Read / Grep / Bash --> F[(ファイル群)]
    S -- 結論だけ --> M
    M --> U

メインから見ると、ファイルの中身や途中の試行錯誤は自分のコンテキストに入らないのがポイントです。そのかわり、サブエージェントはメインの会話の流れを知りません。必要な前提は依頼文に含める必要があります（Claudeが依頼文を組み立てます）。

置き場所と優先順位

同じ名前のエージェントが複数ある場合は、優先順位の高いほうが使われます。

作り方は、Markdownファイルを直接置くか、Claudeに「〜するサブエージェントを .claude/agents/ に作って」と頼むだけです。なお v2.1.198以降、/agents は対話式の作成ウィザードを開かず、作り方の案内を表示するだけになりました。ファイルの形式は変わっていません。編集したファイルは数秒で自動的に読み込まれます。

組み込みのサブエージェント

自分で作らなくても、最初から次のエージェントが用意されています。

「調べるだけ」ならExploreを指名すると、書き込み系のツールを持たないので安心して任せられます。

実測：サブエージェントでメインのコンテキストはどれだけ減るか

検証の条件

使ったサブエージェント（具体的なdescription版）は次のとおりです。

---
name: code-surveyor
description: コードベースの棚卸し専門。複数ファイルを読んで概要・TODO/FIXMEの一覧・件数をまとめる依頼を受けたら、必ずこのエージェントに任せる（use proactively）。読み取り専用。
tools: Read, Grep, Glob
model: haiku
---

あなたはコード棚卸しの担当です。
- 指定範囲のファイルを読み、モジュールごとの概要を1行で書く
- TODO/FIXME をすべて拾い、`ファイルパス:行番号 関数名` の形式で列挙し、総数を数える
- 最終回答は表と総数だけを簡潔に返す（途中経過やファイル全文は返さない）

結果

（A の開始時点が約3,500トークン少ないのは、Agentツールを無効にしたため、その説明文とエージェント一覧が入っていないからです。開始時点の値は環境のツール構成で変わるので、増加分で比べるのがおすすめです。）

サブエージェントに任せたBでは、メインの増加が約1万トークンで、自分で全ファイルを読んだAの約5分の1でした。Bでメインが2回Readしているのは、Claudeが「概要がどのファイルもほぼ同じだったので確認する」と判断して抜き取り確認をしたためです。サブエージェントの報告をうのみにせず確かめる動きも見られました。

一方で、サブエージェントの中ではHaikuが約4.5万トークン分のファイルを読んでいます。全体のトークン量が必ず減るわけではなく、「メインの会話を軽く保つ」ための仕組みと考えるのが正確です。なお model: haiku の指定どおり、サブエージェントの応答はHaikuで生成されていました。

descriptionの書き方で自動委任が変わる

BとCは、本文もツールもモデルも同じで、descriptionだけを変えています。

Claudeは依頼内容とdescriptionを照らし合わせて委任先を決めます。公式ドキュメントでも「use proactively」のような言い回しを入れると積極的に任せやすくなると案内されています。各パターン1回ずつの結果なので確率的な差までは言えませんが、書き方の方向性は次の表のとおりです。

コンテキストの中身は /context で確認できる

対話中は /context で、いまのコンテキストの内訳（システムプロンプト、ツール定義、会話メッセージ、空き容量など）を表で確認できます。claude -p "/context" のように非対話でも動き、この検証環境では次のような表が出ました（抜粋）。

**Tokens:** 35.4k / 500k (7%)

| Category | Tokens | Percentage |
| System prompt | 4.7k | 0.9% |
| System tools | 29.1k | 5.8% |
| Messages | 8 | 0.0% |
| Free space | 431.6k | 86.3% |

大きな調査の前後で /context を見て「Messages」が大きく増えているなら、その種の作業はサブエージェントに任せる候補です。

並列実行：4つのExploreを同時に動かす

依頼文で「別々のサブエージェントで並列に」と指示すると、メインは1回の応答の中でAgentツールを複数同時に呼び出します。実際に次の依頼で試しました。

src/inventory, src/shop, src/users, src/report の4ディレクトリを、それぞれ別の Explore サブエージェントで並列に調査してください。各サブエージェントには、担当ディレクトリの TODO コメントの件数と該当関数名だけを返させ、最後に合計を表にまとめてください。

実行結果の要点は次のとおりです。

返してほしい内容を「件数と関数名だけ」と絞ったことで、メインの増加は3,000トークン弱に収まりました。並列にするときは、担当範囲が重ならないように分けることと、返す形式を指定することの2点を意識すると、まとめやすくなります。

並列数や入れ子には上限があります。

呼び出し方：自動・指名・セッション全体

フォアグラウンドとバックグラウンドも選べます。フォアグラウンドは完了までメインが待ち、バックグラウンドは並行して動いて、完了すると後のターンで通知されます。frontmatterの background: true で常にバックグラウンドにできるほか、実行中に Ctrl+B で切り替えられます。終わったサブエージェントには SendMessage で続きを依頼でき（組み込みのExploreとPlanは除く）、それまでの経緯を引き継いで再開します。

ツール制限とモデル指定の考え方

モデルは「呼び出し時の指定 → frontmatterの model → 環境変数 CLAUDE_CODE_SUBAGENT_MODEL → メインのモデル」の順で決まります。どのモデルで動いたかは /tasks で確認できます。

よくある失敗と対処

なお、使い分けを一言で言うと、CLAUDE.mdやSkillsは「メインに知識や手順を足す」仕組み、サブエージェントは「別の担当者に任せて結果だけ受け取る」仕組みです。

よくある質問

Q. サブエージェントを使うと料金は安くなりますか？ A. 安くなるとは限りません。サブエージェントも自分のコンテキストでファイルを読むため、その分のトークンを使います。実測でも、メインの増加は約5分の1になった一方、サブエージェント側で約4.5万トークンを読み込んでいました。model: haiku のように軽いモデルを指定すると、全体の負担を抑えやすくなります。

Q. サブエージェントはメインの会話やCLAUDE.mdを見られますか？ A. 会話の履歴は見られません。CLAUDE.mdは、ExploreとPlanを除き通常は読み込まれます（omitClaudeMd: true で読み込まないようにもできます）。

Q. 自動で委任されないときは、どうすればよいですか？ A. まずdescriptionを具体的にします。確実に動かしたいときは @agent-名前 で指名するのが確実です。

Q. /agents で作成画面が開きません。 A. v2.1.198以降は仕様として作成ウィザードが開かなくなりました。.claude/agents/ にファイルを置くか、Claudeに作成を頼んでください。

まとめ

• サブエージェントは別のコンテキストで動き、結論だけを返す専門の作業役
• frontmatterの必須は name と description だけ。手順は本文に書く
• 実測では、任せたほうがメインのコンテキスト増加が約5分の1（+47,175 → +9,949）
• descriptionを具体的にすると自動委任され、あいまいだと委任されなかった
• 並列実行は「範囲を分ける」「返す形式を絞る」で、4並列でもメインの増加は3,000トークン弱
• 調査は tools を読み取り系に絞り、軽い作業は model: haiku で任せる
• 全体のトークンが必ず減るわけではない。メインを軽く保つための仕組みとして使う

株式会社RJCでは、AIエージェントに仕事をうまく任せる設計のコツを、プロジェクトの中で仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。