Claude Code のサブエージェントは、別のコンテキストで作業し、結果の要約だけをメインの会話に返す専門の助手です。.claude/agents/ に Markdown を 1 枚置けば作れ、tools と model で権限と費用を絞れます。テスト実行や調査のように途中経過が大量に出る作業を任せると、会話が長持ちします。スキルとの違いも表で整理します。
SNSでシェアして、他のエンジニアにも教えてあげましょう
Claude Code サブエージェント（subagent）は、メインの会話とは別のコンテキストで作業し、結果の要約だけを返してくれる専門の助手です。.claude/ に Markdown のファイルを 1 枚置けば作れます。tools で使えるツールを、model で使うモデルを絞れます1。テストの実行やコードベースの調査のように、途中経過が大量に出る作業を任せると、メインの会話を汚さずに長く作業を続けられます。この記事では、2026 年 10 月時点の公式ドキュメントに沿ってサブエージェントを 1 つ作り、Claude Code v2.1.289 で動かした結果を載せます。得をする場面と損をする場面、スキルとの使い分けも表で整理します。
サブエージェントは、特定の種類の仕事を引き受ける AI の助手です。それぞれが自分のコンテキストウィンドウ、システムプロンプト、使えるツール、権限を持ちます。Claude は依頼の内容とサブエージェントの description を照らし合わせて、合うものに仕事を任せます1。
ポイントは「サブエージェントの中で読んだファイルや実行結果は、メインの会話に入らない」ことです。メインに戻るのは最終報告だけです。公式ドキュメントも、二度と見返さない検索結果やログでメインの会話があふれそうなときに使うよう勧めています1。
Claude Code には、最初から使えるサブエージェントがあります。Claude が状況に応じて自動で使います1。
| 名前 | ツール | 主な用途 |
|---|---|---|
| Explore | 読み取り専用（Write・Edit は使えない） | ファイル探し、コード検索、コードベースの調査 |
| Plan | 読み取り専用 | プランモードで計画を立てる前の調査 |
| general-purpose | サブエージェントで使えるすべてのツール | 調査と変更の両方が要る、複数の手順の作業 |
| claude-code-guide | — | Claude Code の機能についての質問（Haiku で動く） |
| statusline-setup | — | / でステータスラインを設定する（Sonnet で動く） |
Explore と Plan は、軽く速く動かすために CLAUDE.md と git status を読み込みません。Explore を呼ぶとき、Claude は調べる深さを「quick」「medium」「very thorough」から選びます1。
カスタムのサブエージェントは、2025 年 7 月 24 日公開の Claude Code v1.0.60 で作れるようになりました2。v2.1.63 では、サブエージェントを起動するツールの名前が Task から Agent に変わりました。設定に残っている Task(...) という書き方も、別名としてそのまま使えます1。
得をするのは、次の 3 つの場面です13。公式のベストプラクティスも「コンテキストがいちばんの制約なので、調査はサブエージェントに任せてメインの会話から外す」よう勧めています4。
ただし、トークンは増えます。Anthropic が自社の Research 機能について公開した数字があります。エージェントはチャットの約 4 倍、複数のエージェントを使う構成は約 15 倍のトークンを使ったそうです5。
| 使い方 | チャット比のトークン使用量（倍） |
|---|---|
| チャット | 1 |
| 単一のエージェント | 4 |
| マルチエージェント | 15 |
同じ記事では、Claude Opus 4 を指揮役、Claude Sonnet 4 をサブエージェントにした構成が、単体の Claude Opus 4 より社内の調査評価で 90.2% 良い結果だったとも書かれています5。広く並行して調べる作業では効果が大きい一方、コストも増えます。価値の高い作業や、メインの会話を長持ちさせたい作業に絞って使うのが現実的です。Claude Code の公式ドキュメントも、サブエージェントの利用はメインの会話と同じ利用上限にカウントされると明記しています1。
ここでは、テストを実行して失敗だけを報告する test-runner を作ります。前提は Claude Code v2.1.289（2026 年 10 月 3 日公開）です。
サブエージェントは、YAML のフロントマターが付いた Markdown のファイルです。置き場所で使える範囲と優先順位が決まります1。
| 場所 | 範囲 | 優先順位 |
|---|---|---|
| 管理設定（組織） | 組織全体 | 1（最優先） |
--agents フラグ（JSON） | そのセッションだけ | 2 |
.claude/ | そのプロジェクト | 3 |
~/ | 自分のすべてのプロジェクト | 4 |
プラグインの agents/ | プラグインを入れた環境 | 5 |
チームで使うものは .claude/ に置いてコミットするのがおすすめです1。フォルダの中は再帰的に読まれるので、agents/ のようにサブフォルダで整理しても構いません。
.claude/ を作ります。フロントマターで必須なのは name と description だけです。本文がそのままサブエージェントのシステムプロンプトになります1。
---
name: test-runner
description: テストを実行し、失敗したテストと原因だけを短く報告する。テストの実行・失敗の調査を頼まれたら使う。
tools: Read, Grep, Glob, Bash
model: haiku
---
あなたはテスト実行の担当です。
1. `python3 -m unittest -q` でテストを実行する
2. 失敗したテストごとに「テスト名 / エラーの 1 行要約 / 原因と思われる箇所（ファイル:行）」を書く
3. 通ったテストの一覧やログ全文は返さない。コードは書き換えない
サブエージェントが受け取るのは、この本文と作業ディレクトリなどの基本情報だけです。Claude Code 本体のシステムプロンプトは渡りません1。そのため、本文には「何を・どの順で・何を返すか」をはっきり書きます。返す形を決めておくと、メインに戻る要約が短くなります。
description は、Claude が「任せるかどうか」を決める材料です。積極的に使ってほしいなら「use proactively」のような言い回しを入れるよう公式は勧めています1。
tools（使えるツール） は許可リストです。省略すると、サブエージェントで使えるツールをすべて引き継ぎます。逆に「これだけ禁止」にしたいときは disallowedTools を使います1。
# 読み取りと Bash だけ（ファイル編集も MCP ツールも使えない）
tools: Read, Grep, Glob, Bash
# 書き込みだけ禁止し、ほかは引き継ぐ
disallowedTools: Write, Edit
# 特定の MCP サーバーのツールだけ外す
disallowedTools: mcp__github
両方を書くと、先に disallowedTools で外してから tools で絞ります1。なお、AskUserQuestion や EnterPlanMode などは、tools に書いてもサブエージェントには渡りません1。
model（モデル） には sonnet・opus・haiku・fable の別名、claude-opus-5-5 のような完全な ID、または inherit（メインと同じ）を書きます。実際のモデルは次の順で決まります1。
modelmodelCLAUDE_CODE_SUBAGENT_MODELテスト実行や検索のような単純な作業は Haiku、設計レビューのように判断が要る作業は inherit にしておくと、費用と品質のバランスを取りやすくなります。
まず、ファイルが正しく読めるかを確かめます（v2.1.233 以降）1。
claude plugin validate .claude/agents
Validating components in: /private/tmp/write-article/lab/cc-agents/.claude/agents
✔ Validation passed
呼び出し方は 3 つあります1。
| 方法 | 書き方 | 確実さ |
|---|---|---|
| 自然な言葉 | 「test-runner サブエージェントでテストを実行して」 | Claude が任せるかを判断する |
| @ メンション | @"test-runner (agent)" か @agent-test-runner | そのサブエージェントが必ず動く |
| セッション全体 | claude --agent test-runner | メインの会話そのものがそのサブエージェントになる |
下の GIF は、3 件中 1 件が 0 除算で落ちるテストに対して、自然な言葉で頼んだ結果です（実際の出力）。
stream-json の出力で中身を確かめると、メインの会話が呼んだのは Agent ツール 1 回だけでした。サブエージェントの中では ls・find・テスト実行・ファイルの読み込みなど 7 回のツール呼び出しがありましたが、メインに戻ったのは失敗の表だけです。これが「コンテキストの節約」の正体です。
よく使う項目を表にまとめます。複数語の項目名は maxTurns のようなキャメルケースです。知らない名前はエラーなしに無視されるので、綴りに注意してください1。
| 項目 | 役割 |
|---|---|
name・description | 必須。識別名と、いつ任せるかの説明 |
tools・disallowedTools | 使えるツールの許可リスト・禁止リスト |
model・effort | 使うモデルと思考量 |
permissionMode | default・acceptEdits・plan などの権限モード |
maxTurns | 最大ターン数。超えると途中までの結果を返す |
skills | 起動時に本文ごと読み込むスキル |
mcpServers | このサブエージェントだけで使う MCP サーバー |
hooks | このサブエージェントが動いている間だけの hooks |
memory | user・project・local で、会話をまたいで残るメモ帳を持たせる |
isolation | worktree で、一時的な git worktree の中で作業させる |
background | true で常にバックグラウンドで動かす |
omitClaudeMd | true で CLAUDE.md を読み込まずに起動する |
mcpServers に MCP サーバーを直接書くと、そのツールの説明はメインの会話に入りません。ブラウザ操作のようにツール数の多いサーバーを、必要なサブエージェントだけに持たせられます1。
いちばん効果がわかりやすいのは、テストの実行です。公式ドキュメントにも「サブエージェントでテストを実行し、失敗したテストとエラーだけを報告して」という例があります1。上の test-runner のように返す形を決めておけば、テストが数百件あってもメインに戻るのは数行です。テスト駆動で進める具体例は「Claude Code で Go のテスト駆動開発」でも紹介しています。
「認証・データベース・API のモジュールを、別々のサブエージェントで並列に調べて」と頼むと、Claude は 3 つを同時に動かし、結果をまとめます1。調べる道筋が互いに依存しないときに向いています。ただし、各サブエージェントの報告はすべてメインに戻ります。詳しい報告を返す並列作業を増やしすぎると、かえってコンテキストを圧迫します1。
「code-reviewer でパフォーマンスの問題を探し、そのあと optimizer で直して」のように順番に使うこともできます。Claude が前のサブエージェントの結果から必要な部分を次に渡します1。レビュー担当は tools: Read, Grep, Glob, Bash にして編集させず、修正担当にだけ Edit を渡すと、役割がはっきりします。
ツールを Bash だけにしても、Bash で何でもできてしまいます。公式の例では、PreToolUse の hook で SQL の書き込み系の文を見つけたら終了コード 2 で止め、SELECT だけを許しています1。
---
name: db-reader
description: 読み取り専用のデータベースクエリを実行する
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
hooks の書き方そのものは「Claude Code の hooks 入門」で解説しています。
サブエージェントとスキルは、似ているようで解く問題が違います。公式の比較をもとに整理します36。
| スキル | サブエージェント | |
|---|---|---|
| 正体 | 再利用できる指示・知識・手順 | 自分のコンテキストを持つ独立した作業者 |
| コンテキスト | メインの会話に足される | 別のウィンドウで動き、要約だけ戻る |
| 会話の履歴 | 見える | 見えない（任されたメッセージだけ） |
| 置き場所 | .claude/ | .claude/ |
| 呼び出し | / か自動 | 自然な言葉、@ メンション、--agent か自動 |
| 向いている作業 | 手順書、規約、呼び出せるワークフロー | 大量に読む作業、並列作業、権限を絞った作業 |
2 つは組み合わせられます。サブエージェントの skills に書けば、スキルの本文を起動時に読み込ませられます。逆に、スキルに context: fork を付けると、スキルの本文を指示としてサブエージェントが動きます6。スキルの作り方は「Claude Code スキルの作り方」で詳しく扱っています。
メインの会話のままのほうがよい場面もあります。公式は次のような作業はメインの会話で進めるよう勧めています1。
いまの会話の中身について質問したいだけなら、/ が使えます。会話をすべて見たうえで答え、その答えは履歴に残りません1。
サブエージェントは、メインの会話の履歴も、すでに読んだファイルも、呼び出したスキルも見えません。Claude が書く「任せるメッセージ」だけを頼りに作業します1。「vendor/ は無視する」のように必ず伝えたいことは、頼むときに書きます。会話の内容をそのまま引き継がせたいときは、/ で会話を丸ごと引き継ぐ「フォーク」を使います1。
組み込みの Explore と Plan 以外のサブエージェントは、CLAUDE.md を読み込みます。自作のサブエージェントで読ませたくないときは omitClaudeMd: true を付けます（v2.1.271 以降）1。CLAUDE.md の書き方は「CLAUDE.md の書き方と AGENTS.md との違い」を参照してください。
バックグラウンドで動くサブエージェントは、Read・Grep・Bash・Edit・Write・WebFetch など決まった組み込みツールしか使えません。対話セッションでは既定でバックグラウンドになるので、前景と同じ定義でもツールが変わることがあります1。
~/ などのフォルダが、セッション開始時に無かった場合は再起動が必要です。フォルダがあれば、ファイルの追加や編集は数秒で反映されます1。また、フロントマターに name が無い、description が無い、YAML が壊れている、といったファイルは何も表示されずに読み飛ばされます。claude --debug で理由を確かめられます1。
description の合計が 15,000 トークンを超えると、起動時に警告が出ます1Concurrent subagent limit reached になります1hooks・mcpServers・permissionMode は無視されます1.claude/ を置けば作れるtools で権限を、model で費用を絞る。単純な作業は Haiku、判断が要る作業は inherit次にやることとして、いつもログが長くなる作業（テスト、ビルド、ログ調査）を 1 つ選び、返す形を決めたサブエージェントにしてみてください。
スキルは「メインの会話に読み込む手順や知識」で、サブエージェントは「別のコンテキストで動く作業者」です。スキルの中身は会話に足され、サブエージェントの作業は会話に入らず要約だけが戻ります3。スキルに context: fork を付けると、スキルをサブエージェントとして動かせます6。
呼び出し時に渡された model、フロントマターの model、環境変数 CLAUDE_CODE_SUBAGENT_MODEL、メインの会話のモデルの順に決まります1。動いているモデルは / で確かめられます。
動かせます。「別々のサブエージェントで並列に調べて」と頼むと、Claude が同時に起動します。同時に動かせる数は既定で 20 個で、環境変数 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変えられます1。
できます。終わったサブエージェントには ID が付き、Claude は SendMessage で同じサブエージェントを再開できます。履歴は引き継がれます1。ただし、組み込みの Explore と Plan は 1 回きりで、再開できません。
増えます。サブエージェントは自分でリクエストを送り、メインの会話と同じ利用上限にカウントされます1。Anthropic の実測では、複数のエージェントを使う構成はチャットの約 15 倍のトークンを使いました5。単純な作業は model: haiku にすると抑えられます。
Create custom subagents — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 ↩17 ↩18 ↩19 ↩20 ↩21 ↩22 ↩23 ↩24 ↩25 ↩26 ↩27 ↩28 ↩29 ↩30 ↩31 ↩32 ↩33 ↩34 ↩35 ↩36 ↩37 ↩38 ↩39 ↩40 ↩41 ↩42
Claude Code CHANGELOG（1.0.60） — Anthropic, GitHub（v1.0.60 の公開日は npm レジストリの記録で 2025-07-24）（2026-10-05 参照） ↩
Extend Claude Code（Skill vs Subagent） — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩ ↩2 ↩3
Best practices for Claude Code（Use subagents for investigation） — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩
How we built our multi-agent research system — Anthropic Engineering, 2025-06-13（2026-10-05 参照） ↩ ↩2 ↩3
Extend Claude with skills（Run skills in a subagent） — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩ ↩2 ↩3