【実演】Claude Codeのサブエージェント使い分けガイド｜3階層まで呼べる新仕様も解説
Xで見た「サブエージェントは3種類」という投稿、実は不正確だった
Xで「Claude Codeには最初からサブエージェント（別枠で動く専用AI）が3種入ってる。Explore・Plan・general-purposeで、複雑な検索はExploreに投げれば自作不要」という投稿を見かけた。実際にリプライでもこの話題に触れたことがあるが、改めて公式ドキュメントで裏取りしてみると、この「3種類」という数字は正確ではなかった。
この記事では、ビルトインのサブエージェントが実際には何種類あるのか、カスタムのサブエージェントをどう作るのか、そして最近追加された「サブエージェントが3階層まで別のサブエージェントを呼べる」という新仕様まで、公式ドキュメントで確認した範囲だけをまとめた。
自分がサブエージェントを意識するようになったのは、記事のネタ探しでXの投稿を大量に検索するようになってからだった。検索結果を1件ずつメインの会話に読み込ませると、それだけで文脈がすぐに埋まってしまう。調べ物をサブエージェントに任せて、結論だけを持ち帰ってもらうようにしてから、この悩みがかなり解消された。今回はその「なんとなく便利」で終わらせていた部分を、公式ドキュメントで正確に裏取りする作業でもある。
ビルトインサブエージェントは実は4〜5種類ある
Claude Codeに最初から組み込まれているサブエージェントは、確認できただけで次の通りだった。
Explore・Plan・general-purposeの3つに加えて、statusline-setup（/statuslineコマンド実行時に呼ばれる）、claude-code-guide（Claude Code自体についての質問に呼ばれる）が存在する。用途によって自動的に切り替わる仕組みで、常に全部が並んでいるわけではないが、少なくとも「3種類しかない」という理解は正確ではない。
ExploreとPlanは高速・低コストが重視されていて、CLAUDE.mdの読み込みやGitステータスの確認をスキップするようになっている。裏を返すと、この2つは「深く考える」用途ではなく「素早く調べる」用途に最適化されているということになる。
statusline-setupとclaude-code-guideは常に選択肢に出てくるわけではなく、対応するコマンドや質問をしたときだけ裏側で呼ばれる、いわば専用エージェントに近い。これらは自分でモデルを選んだり構成を調整したりする対象ではなく、決まった用途のために最初から用意されている、と理解しておけば十分だった。
Explore・Plan・general-purposeの使い分け
実際の役割はそれぞれ違う。Exploreはコードベースの検索やファイル探索を高速でこなす読み込み専用のサブエージェントで、探索の詳細度（さっと調べる／中程度／じっくり網羅的に調べる）をClaude自身が自動で判断する。
Planは計画モード専用で、プランを立てる前のリサーチをメインの会話から隔離するために使われる。探索の過程で出てくる大量の中間結果が、メインの会話のコンテキストを圧迫しないようにする役割を持つ。
general-purposeは探索と実装の両方を扱える汎用型で、複雑で複数ステップにまたがるタスクに向いている。困ったらこれに任せておけば動く、という位置づけに近い。
使い分けの目安として、自分では次のように整理している。単純に「このファイルの中身を知りたい」だけならメインの会話で直接読む。「このキーワードがどこで使われているか、コードベース全体から探したい」ならExplore。「実装方針を固める前に、選択肢を整理してほしい」ならPlan。「調査から実装まで一通りまとめて任せたい」ならgeneral-purpose、という具合だ。境界線が曖昧なときは、まずExploreに軽く投げてみて、範囲が広がりそうならgeneral-purposeに切り替える、というやり方が事故が少ない。
新仕様：サブエージェントは最大3階層まで呼べる
今回調べていて一番驚いたのがこの仕様だった。デフォルトでは、サブエージェントがさらに別のサブエージェントを生成できる階層は最大3階層までになっている。この上限は最近のバージョンから3に設定されたもので、それ以前はもっと制限的だった。
階層の上限に達すると、その階層のサブエージェントからはさらに別のサブエージェントを呼ぶ手段（Agentツール）が取り除かれ、自力でタスクを完了させて結果を返す仕組みになっている。上限は環境変数で調整でき、1に設定すればサブエージェントからの追加生成そのものを禁止できる。
実際、この記事の調査自体もサブエージェント（claude-code-guide）に任せて公式ドキュメントを読んでもらう形で進めている。メインの会話に検索過程の細かいログを持ち込まずに、必要な結論だけを受け取れるのは、日常的に使っていて便利だと感じる部分だ。
3階層まで許されている、というのは裏を返すと「無限に入れ子にできるわけではない」ということでもある。調べ物を任せたサブエージェントが、さらに別のサブエージェントに丸投げし、そのサブエージェントがまた別のサブエージェントを呼ぶ、というのを無制限に続けられると、何が起きているのか誰にも追えなくなる。3という具体的な上限が引かれているのは、便利さと制御可能性のバランスを取った結果なのだろうと感じた。
カスタムサブエージェントの作り方
自分でサブエージェントを作りたい場合は、プロジェクト単位なら`.claude/agents/`、個人の全プロジェクト共通で使いたい場合は`~/.claude/agents/`にMarkdownファイルを置く。
必須なのはnameとdescriptionの2つだけで、あとはtools（使えるツールの制限）、model（使うモデルの指定）、permissionMode（権限モード）などをオプションで足せる。ファイルを置くと数秒で自動的に認識され、セッションを再起動する必要はない。
正直に書いておくと、自分はこの記事を書くまでカスタムサブエージェントを一度も作っていなかった。`.claude/agents/`ディレクトリ自体が存在しない状態で、ビルトインのExplore・Plan・general-purposeだけで日々の記事執筆やX・noteの運用作業は十分にこなせていた。カスタムサブエージェントは「同じ役割のエージェントを繰り返し使う」場面で効いてくるもので、最初から作る必要はないというのが実感に近い。
たとえばtools欄で使えるツールを絞っておけば、「このサブエージェントは読み込みしかしない」という制約を最初から保証できる。permissionModeを組み合わせれば、確認なしで進めてよい範囲もサブエージェント単位でコントロールできる。毎回同じ役割を口頭で説明し直すのが面倒になってきたタイミングが、カスタムサブエージェントを作る目安になりそうだと感じている。
サブエージェントに使うモデルを個別指定する方法
frontmatterのmodelフィールドで、サブエージェントごとに使うモデルを指定できる。sonnet・opus・haiku・fableのようなエイリアスでも、正式なモデル名でも指定でき、省略した場合は親のセッションと同じモデルを引き継ぐ。
重い処理を任せるサブエージェントには上位モデルを、単純な検索を任せるサブエージェントには軽量なモデルを割り当てる、という使い分けが可能ということになる。Claude Codeのモデル使い分けガイドで書いたモデル選択の考え方は、この個別指定にもそのまま応用できる。
並列実行の上限と注意点
複数のサブエージェントを同時に走らせることもできる。デフォルトでは同時に実行できるのは最大20個までで、1つのセッション全体を通して生成できる総数は最大200個までという上限がある。どちらも環境変数で変更可能だが、上限そのものが存在することは知っておいたほうがいい。
公式ドキュメントにも注意書きがあり、複数のサブエージェントが大量の結果を一斉に返すと、それを受け取るメインの会話側のコンテキストがまとめて消費されてしまう。AIに渡す情報を実際に68%削った全記録でも触れたが、AIに渡す情報は「増やす」より「絞る」ほうが結果的にうまくいくことが多く、サブエージェントを並列で使うときも、返してもらう情報を要点だけに絞る意識が要る。
実際に自分の運用で使っているサブエージェント
普段の運用では、ネタ探しや仕様の裏取りのような「調べて結論だけ持ち帰ってほしい」作業をExploreやclaude-code-guideに任せ、記事の構成案を練るような「行き来しながら詰めていきたい」作業はメインの会話でそのまま進めることが多い。
この使い分けの基準は公式ドキュメントの説明ともおおむね一致していて、頻繁なやり取りや大きなコンテキスト共有が必要な作業はメイン会話に残し、自己完結していて出力だけ受け取れればいい作業をサブエージェントに渡す、という整理がしっくりきている。
この記事自体、Xのバズ投稿を検証する段階でclaude-code-guideサブエージェントに公式ドキュメントを読みに行ってもらい、戻ってきた要点をもとに構成を組み立てている。調査の過程で読んだページ数や試行錯誤はサブエージェント側に留まり、メインの会話には結論だけが残る。この分業が、記事を書くスピードにも地味に効いていると感じる。
よくある質問（FAQ）
Q. サブエージェントは何種類ありますか？
A. ビルトインだけでExplore・Plan・general-purpose・statusline-setup・claude-code-guideの5つを確認できた。Xで見かけた「3種類」という説明は、代表的な3つだけを指した簡略化だったと考えられる。
Q. サブエージェントがさらにサブエージェントを呼ぶことはできますか？
A. できる。デフォルトで最大3階層まで、サブエージェントが別のサブエージェントを生成できる。上限に達すると、その階層はそれ以上サブエージェントを呼べなくなり、自力でタスクを完了させて結果を返す。
Q. カスタムサブエージェントは必ず作るべきですか？
A. 必須ではない。同じ役割の作業を繰り返す場面が出てきてから作るのでも十分間に合う。自分自身、この記事を書くまでカスタムサブエージェントを1つも作っていなかった。
Q. サブエージェントに使うモデルは変えられますか？
A. frontmatterのmodelフィールドで個別指定できる。省略すると親セッションと同じモデルを引き継ぐ。
Q. サブエージェントを使いすぎるとどうなりますか？
A. 同時実行数とセッション全体の生成数の両方に上限があるため、無制限に増え続けることはない。ただしサブエージェントが返す結果が大きいと、それを受け取るメインの会話のコンテキストは消費されるので、返してもらう情報量は絞ったほうがいい。
まとめ
Xで見かけた「サブエージェントは3種類」という説明は、実態としてはやや簡略化されたものだった。実際にはビルトインだけで5種類前後があり、さらに最近の仕様変更で、サブエージェントが3階層までさらに別のサブエージェントを呼べるようになっている。
カスタムサブエージェントを作る必要は必ずしもなく、まずはExplore・Plan・general-purposeの3つの役割を理解して使い分けるところから始めれば十分だった、というのがこの記事を書いての実感になる。バズった投稿の数字をそのまま鵜呑みにせず、手元のドキュメントと実際の挙動で裏を取る一手間が、結果的に一番確実な近道だった。
あわせて読みたい関連記事：
AIの最新情報をリアルタイムで発信中
Claude Codeを中心としたAI活用の実践ノウハウは、X（@ai_hack_dx）でも毎日発信している。今回のような機能検証の結果や、記事にする前の小さな発見はXのほうが先に流れることが多いので、続きが気になる方はぜひフォローしてほしい。
