はじめに:「サブエージェントを使って」と言ったことはありますか?
Claude Code で少し大きめの調査を頼むと、画面に Explore(…) や 3 background agents launched といった表示が出ることがあります。これがサブエージェントです。メインの Claude が、仕事の一部を「助手」に任せている合図です。
ただ、次のような疑問を持ったまま使っている方も多いのではないでしょうか。
- 最初から入っている助手には、どんな種類があるの?
- 自分で指名して呼び出すには、どう書けばいい?
- 自分専用の助手は、どうやって作るの?
/agentsと打ったら「wizard has been removed」と出たんだけど…?
この記事では、公式ドキュメントの現在の記載(2026年9月21日時点)と、筆者の環境(Claude Code v2.1.272)での実際の画面をもとに、サブエージェントの使い方を順番に説明します。プログラミングに詳しくない方でも追えるよう、専門用語には短い説明を添えます。
「そもそもシングルエージェント・サブエージェント・マルチエージェントって何が違うの?」という方は、先に概念編「シングル・サブ・マルチエージェントの違いを『作業机』で理解する」をどうぞ。
30秒でおさらい:サブエージェントは「自分専用の机を持つ助手」
AIには、一度に覚えておける量の上限(コンテキストウィンドウ。この記事では「作業机」と呼びます)があります。検索結果やログを大量に読むと、机がそれで埋まってしまいます。
サブエージェントは、自分専用の机・専用の指示・使える道具の制限を持った助手です。散らかる作業を助手の机でやってもらい、メインには要約だけを返してもらいます。公式ドキュメントは、その効果を次の5つにまとめています。
- コンテキストを保持する(探索や実装の細部を、メインの会話から切り離す)
- 制約を強制する(使える道具を制限する)
- 設定を再利用する(一度作った助手を、どのプロジェクトでも使う)
- 動作を特化させる(分野ごとの専用の指示を持たせる)
- コストを制御する(軽いモデルに仕事を回す)
画面1:公式ドキュメント「カスタムサブエージェントの作成」の冒頭(2026年9月21日に取得)。出典: code.claude.com/docs/ja/sub-agents
最初から入っているサブエージェントは、主役3つ+裏方3つ
Claude Code には、何も設定しなくても使える組み込みサブエージェントがあります。まず全体の地図を見てください。上の段の3つが主役です。
図1:組み込みサブエージェントの地図。ふだん意識するのは上の3つだけで十分です。(静止画版)
表にすると、次のとおりです。
| 名前 | 役割 | 使える道具 | モデル |
|---|---|---|---|
| Explore | コードを検索して理解する探索係 | 読み取り専用(Write・Editは拒否) | メインの会話から継承(Claude APIではOpusが上限) |
| Plan | プランモード中の下調べ係 | 読み取り専用(Write・Editは拒否) | メインの会話から継承 |
| general-purpose | 調査と変更の両方が要る、複雑な多段階タスクの何でも係 | サブエージェントが使える全ツール | 基本はメインの会話と同じ |
| claude-code-guide | Claude Code の機能についての質問に答える | ― | Haiku |
| statusline-setup | /statusline でステータスラインを設定する | ― | Sonnet |
| claude | どの専門家にも当てはまらない仕事の受け皿。バックグラウンドセッションの既定 | 全ツール | モデルの決定順に従う |
Explore:いちばん出番が多い探索係
「変更は加えずに、コードを調べたい・理解したい」ときに Claude が使います。呼び出すとき、Claude は徹底度を3段階(quick=狙いを絞った検索/medium=バランス型/very thorough=網羅的な分析)から指定します。
画面2:公式ドキュメントの「組み込みサブエージェント」(Exploreタブ)。出典: code.claude.com/docs/ja/sub-agents
古い情報に注意: 以前の Explore は常に Haiku(軽量モデル)で動いていましたが、公式ドキュメントによると v2.1.198 以降はメインの会話のモデルを継承します(Claude API では Opus が上限)。「探索は安いモデルのままがいい」という場合は、Explore という名前のサブエージェントを自分で定義して model: haiku と書けば、組み込みを上書きできます。
もう1つ、Explore と Plan はCLAUDE.md(プロジェクトの指示書)と git の状態を読み込まずに起動します。調査を速く・安くするための仕様です。「CLAUDE.md に書いたルールを Explore が守らない」と感じたら、これが理由です。
Plan:プランモードの下調べ係
プランモード(変更を加えずに計画だけ立てるモード)の最中に、Claude がコードベースを理解する必要が出たとき、調査を Plan に任せます。調査の出力は Plan の机にとどまり、メインの会話は読み取り専用のまま計画づくりに集中できます。
general-purpose:調査も変更もできる何でも係
タスクが「調べる」と「書き換える」の両方を必要とするとき、結果の解釈に複雑な推論が要るとき、依存し合う複数のステップがあるときに使われます。「サブエージェントを使って」とだけ頼むと、これが選ばれることが多いです。
裏方のヘルパー
残りの3つは、通常は自動で呼び出されるので、直接使う必要はありません。
画面3:公式ドキュメントの「組み込みサブエージェント」(Otherタブ)。statusline-setup は Sonnet、claude-code-guide は Haiku で動くと書かれています。
使ってみる①:まずは「おまかせ」で Explore を動かす
論より証拠です。小さな家計簿CLI(CSVの支出データを集計する Node.js のプログラム)を用意して、実際に頼んでみました。入力したのは、この1行だけです。
Exploreサブエージェントを使って、このプロジェクトのファイル構成と処理の流れを調べて、3行で教えて
すると、会話の中に Explore(プロジェクト構成と処理フロー調査) という行が現れます。これが委任の合図です。入力欄で ↓ キーを押すと、下にパネルが開き、動いているサブエージェントが一覧で見えます。
画面4:実際の画面(筆者の環境で取得)。下のパネルで、Explore が自分の机で 18.8k トークンを使って調査中だと分かります。
27秒後、Explore の報告が届き、メインがそれを3行にまとめて答えました。
画面5:Explore の報告をメインがまとめた結果。cli.js:5 のように、根拠の行番号つきで返ってきます。
ここで起きたことを、図で整理します。②(まっさらな机で起動)と④(最後の報告だけ返す)が、サブエージェントを理解するうえで一番大事なところです。
図2:呼ばれてから結果が戻るまで。入れ子は既定でメインの下3層までです。(静止画版)
補足を2つ。
- 子は会話履歴を引き継ぎません。 届くのは、親の Claude が書いた依頼文と、その子専用の指示だけです。
- 続きを頼めるのは一部だけ。 general-purpose やカスタムのサブエージェントは、前回の文脈を持ったまま再開できます。一方、Explore と Plan は再開できません。
使ってみる②:呼び出し方は4通り
呼び出し方は、確実さの違いで4段階あります。
図3:4つの呼び出し方。まずは①で十分です。(静止画版)
| 方法 | 書き方の例 | どんなときに |
|---|---|---|
| ① おまかせ | このプロジェクトの構成を調べて | ふだんはこれ。Claude が説明文(description)を見て判断 |
| ② 名前を出す | test-gap-finder エージェントを使って parse.js を見て | 使ってほしい助手が決まっているとき(最終判断は Claude) |
| ③ @メンション | @"test-gap-finder (agent)" parse.js のテストは足りていますか? | 必ずその助手を動かしたいとき |
| ④ セッション全体 | claude --agent test-gap-finder | メインの会話そのものを、その助手の指示と道具で動かしたいとき |
③の @メンションは、入力欄で @ に続けて名前を打ちはじめると候補が出ます。ファイルの候補と並んで、(agent) と付いた行が出るのが目印です。
画面6:@test-gap まで打ったところ。* test-gap-finder (agent) の行がサブエージェントの候補です(上下の行は同名ファイルの候補)。
公式ドキュメントにも、この書式が載っています。
画面7:公式ドキュメント「サブエージェントを明示的に呼び出す」。出典: code.claude.com/docs/ja/sub-agents
並列で動かす
「3つ並列で」と数を伝えれば、同時に複数の助手を出せます。
サブエージェントを3つ並列で使って、src/cli.js・src/parse.js・src/summary.js をそれぞれ1行で要約して
画面8:3体の Explore が同時に動いている画面。終わった順に完了通知が届き、最後にメインが3つの要約をまとめます。
公式ドキュメントによると、同時に動かせるサブエージェントは既定で20体まで、入れ子(サブエージェントがさらにサブエージェントを呼ぶ)は既定でメインの下3層までです。入れ子の上限は、環境変数 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変えられます(以前のバージョンでは最大5層の時期がありましたが、公式ドキュメントによると v2.1.219 以降の既定は3層です)。
フォアグラウンドとバックグラウンド
サブエージェントの動かし方には、「前で待つ」と「裏で走らせる」の2つがあります。
図4:2つの実行方法の違い。実行中のタスクは Ctrl+B でバックグラウンドに回せます。(静止画版)
筆者の環境では、今回頼んだサブエージェントはすべて Backgrounded agent と表示され、バックグラウンドで起動しました。その間もメインの会話は止まらず、「結果はまだ届いていません。完了通知が来たらお伝えします」と正直に報告してくれます。
使ってみる③:自分専用のサブエージェントを作る
同じ種類の仕事を、同じ指示で何度も頼むなら、カスタムサブエージェントにしておくと便利です。
/agents の作成ウィザードは、なくなりました
少し前の解説記事では「/agents コマンドで対話的に作る」と紹介されていることが多いのですが、現在は違います。実際に打ってみた結果がこちらです。
画面9:v2.1.272 で /agents を実行した結果。公式ドキュメントにも、v2.1.198 以降は作成ウィザードが開かなくなったと書かれています。
いまの作り方は、次の3通りです。
- Claude に頼む(「テストの抜けを探す読み取り専用のサブエージェントを作って」)
- Markdown ファイルを自分で書く
--agentsオプションで、起動時に JSON で一時的に定義する
ファイルの場所・書式は以前と変わっていません。なくなったのは、ターミナル上の作成画面だけです。
正体は Markdown ファイル1枚
今回は、2の「自分で書く」で作りました。プロジェクトの中に .claude/agents/ フォルダを作り、次のファイルを置きます。「指定された関数にテストが足りているかを調べる、読み取り専用の助手」です。
---
name: test-gap-finder
description: テストの抜け漏れを探す読み取り専用エージェント。関数やファイルを指定して「テストは足りている?」「どこが未テスト?」と聞かれたときに使う。コードは変更しない。
tools: Read, Grep, Glob
model: haiku
color: green
---
あなたはテストの抜け漏れを見つける担当です。コードは一切変更しません。
1. 指定されたファイル(なければ src/ 全体)の公開関数を洗い出す
2. test/ を検索し、各関数に対応するテストがあるか確認する
3. 次の形式で、日本語で短く報告する
- テスト済み: 関数名(テストファイル:行)
- 未テスト: 関数名 — 追加したいテストケースを1行で
- 優先度が一番高い1件とその理由
このファイルの読み方を、図で確認しましょう。
図5:上半分(--- で囲んだフロントマター)が設定、下半分がそのままシステムプロンプト(その助手への常設の指示)になります。(静止画版)
一番大事なのは description です。Claude はこの文を読んで「いつこの助手に任せるか」を決めます。「何をする助手か」だけでなく、「どんな質問をされたときに使うか」まで書くのがコツです。
呼び出してみる
@メンションで指名して、質問してみます。
画面10:自作の test-gap-finder が起動したところ。下のパネルにも自作の名前で表示されます。
43秒後、決めた形式に近い形で報告が返ってきました。
画面11:自作サブエージェントの報告をメインがまとめた結果。tools に編集系の道具を入れていないので、ファイルは変更されません。
主なフロントマターの項目
必須は name と description の2つだけです。よく使う任意項目を表にまとめます(公式ドキュメントの一覧から抜粋)。
| 項目 | 必須 | 意味 |
|---|---|---|
name | はい | 呼び名。小文字とハイフン |
description | はい | Claude がいつ任せるかの判断材料 |
tools | いいえ | 使える道具の許可リスト。省略すると全部を継承 |
disallowedTools | いいえ | 使わせない道具の拒否リスト |
model | いいえ | sonnet/opus/haiku/fable/完全なモデルID/inherit(親と同じ) |
permissionMode | いいえ | 権限モード(default、acceptEdits、plan など) |
maxTurns | いいえ | 作業の往復回数の上限 |
skills | いいえ | 起動時に読み込ませるスキル |
mcpServers | いいえ | この助手だけに使わせる MCP サーバー |
memory | いいえ | セッションをまたぐ記憶の保存先(user/project/local) |
isolation | いいえ | worktree を指定すると、隔離された作業用コピーで実行 |
effort | いいえ | 推論の努力レベル(low〜max) |
color | いいえ | 画面上の表示色 |
画面12:公式ドキュメントのフロントマター一覧。全項目と最新の仕様は、こちらを確認してください。出典: code.claude.com/docs/ja/sub-agents
置き場所と優先順位
ファイルをどこに置くかで、「誰が使えるか」が決まります。同じ名前の定義が複数の場所にあるときは、優先度の高いものが使われます。
図6:置き場所と優先順位。チームで共有するならプロジェクト、自分専用ならユーザーに置きます。(静止画版)
ファイルに残さず、その場かぎりで試したいときは --agents が便利です。次のように、起動時に JSON で渡します(書式は公式ドキュメントの例に合わせています。筆者はこのコマンドの実行までは検証していません)。
claude --agents '{
"test-gap-finder": {
"description": "テストの抜け漏れを探す読み取り専用エージェント。",
"prompt": "あなたはテストの抜け漏れを見つける担当です。コードは変更しません。",
"tools": ["Read", "Grep", "Glob"],
"model": "haiku"
}
}'
サブエージェントに向く仕事・向かない仕事
公式ドキュメントの指針を、判断しやすい形に整理します。
サブエージェントに任せるとよい仕事
- テスト実行、ログ調査、ドキュメント探しなど、出力が長くなる作業
- 「読むだけ」に道具を制限したいレビューや調査
- それだけで完結していて、要約だけ戻ればよい作業
- 互いに独立していて、並列に進められる複数の調査
メインの会話のまま進めたほうがよい仕事
- 何度も細かくやり取りしながら詰めていく作業
- 計画→実装→テストで、文脈を濃く共有する作業
- すぐ終わる小さな修正(サブエージェントは起動時に状況を集め直すので、かえって遅くなります)
なお、「いまの会話の中身について、ちょっと聞きたいだけ」なら、公式ドキュメントはサブエージェントではなく /btw を勧めています。会話の全文脈を見たうえで答えてくれて、その答えは履歴に残りません。
うまく動かないときの確認順
つまずいたときは、上から順に確認します。
図7:つまずいたときの確認順。(静止画版)
| 症状 | 原因として多いもの | 対処 |
|---|---|---|
| 作ったのに候補に出ない | ファイルの1行目が --- でない/name か description がない | 書式を直す。Claude Code は name のないファイルを説明用の文書とみなして読み飛ばします |
| 直しても出ない | .claude/agents/ フォルダをセッション開始後に初めて作った | Claude Code を起動し直す(既存フォルダ内の追加・編集は、数秒で自動検出されます) |
| 別の助手が選ばれる | description があいまい | 「どんな依頼のときに使うか」を具体的に書く。急ぐなら @メンション |
| CLAUDE.md のルールを Explore が守らない | Explore と Plan は CLAUDE.md を読み込まない仕様 | ルールを依頼文に書く、または CLAUDE.md を読むカスタムの助手を使う |
| 的外れな報告が返る | 子は会話履歴を知らない | 依頼に「目的・対象ファイル・返してほしい形」を入れる |
| 遅い・トークンが増える | 小さな作業まで委任している | 小さな作業はメインで。調査用は model: haiku などで軽く |
もう1つ、画面11をよく見ると、メインの Claude が「ファイルは変更していません」と報告の出どころを明示しています。サブエージェントの報告は便利ですが、あくまで要約です。大事な判断の前には、根拠のファイルと行を確認する習慣をつけると安心です。
発展:サブエージェントで足りなくなったら
サブエージェントは「親が頼み、子が要約を返す」一方向の分業です。次のような場面では、別の仕組みが向いています。
- 担当どうしで相談や反証をさせたい → エージェントチーム(実験的機能。既定では無効)
- 数十〜数百の独立作業に割って、検証まで任せたい → 動的ワークフロー(
ultracode、/workflows、/deep-research)
公式ドキュメントの概要ページに、使い分けの比較表があります。
画面13:公式ドキュメント「エージェントを並列実行する」の比較表。出典: code.claude.com/docs/ja/agents
それぞれの違いと選び方は、概念編で図つきで説明しています。
まとめ
- 組み込みサブエージェントの主役は Explore(探索)・Plan(計画の下調べ)・general-purpose(何でも係) の3つ。裏方に claude-code-guide、statusline-setup、claude がいます。
- Explore は v2.1.198 以降、メインのモデルを継承します(「常に Haiku」は古い情報です)。
- 呼び出し方は おまかせ → 名前を出す → @メンション →
claude --agentの4段階。確実に動かしたいなら @メンションです。 /agentsの作成ウィザードは廃止されました。いまは Claude に頼むか、.claude/agents/に Markdown を置きます。- カスタムサブエージェントの決め手は description。「いつ使うか」まで書きます。
- 子は会話履歴を引き継ぎません。依頼には目的・対象・返してほしい形を入れます。
最初の一歩は、読み取り専用の Explore を1回呼んでみることです。ファイルが書き換わる心配がないので、いま開いているプロジェクトで気軽に試せます。
Exploreサブエージェントを使って、このプロジェクトのファイル構成と処理の流れを調べて、3行で教えて
参考リソース
- Claude Code 公式ドキュメント「カスタムサブエージェントの作成」 https://code.claude.com/docs/ja/sub-agents
- Claude Code 公式ドキュメント「エージェントを並列実行する」 https://code.claude.com/docs/ja/agents
- Claude Code 公式ドキュメント「Claude Code セッションのチームを調整する」 https://code.claude.com/docs/ja/agent-teams
- Claude Code 公式ドキュメント「動的ワークフローで大規模にサブエージェントをオーケストレーションする」 https://code.claude.com/docs/ja/workflows
- Anthropic「How we built our multi-agent research system」 https://www.anthropic.com/engineering/multi-agent-research-system
検証環境: macOS / Claude Code v2.1.272 / Claude Max。画面4・5は Fable 5.1、画面6・8・10・11は Sonnet 5 のセッションで取得しました。ターミナル画面は、実際に端末へ出力された文字と色を再描画したものです(OSのスクリーンショットではありません。利用上限の通知など、本題と関係のない行は省いています)。公式ドキュメントの画面は2026年9月21日時点の表示です。
