「コードベース全体を調べて、認証周りの呼び出し関係を全部マップして」── そういう調査を Claude にメイン会話で頼むと、関係するファイルが次々読み込まれてコンテキストが一気に埋まる。基礎で予告したサブエージェントは、こういう仕事をメインから切り離すための仕組みである。

本章では実践の閉じとして、サブエージェントを呼び出す側の基本を扱う。自分でサブエージェントを定義する話は応用に送る。

サブエージェントとは何か

サブエージェントは、特定のタスク向けに特化した Claude のインスタンスで、独自のコンテキストウィンドウで動く。メイン会話とは別の文脈を持ち、独立した権限で動作し、終わると結果のサマリーだけをメインに返す。

ポイントは「サマリーだけ返ってくる」こと。サブエージェントが何百ファイル読もうが、何百行のログを処理しようが、メイン会話に届くのは数行〜十数行のまとめである。こちらの会話を汚さずに大きな仕事を任せられる。

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

Claude Code には最初からいくつかのサブエージェントが組み込まれていて、Claude が必要に応じて自動的に使う。明示的に呼ばなくても、すでにこれらが裏で動いていることがある。

Explore

コードベースの検索と分析に特化した、高速で読み取り専用のサブエージェント。Haiku モデルで動くため軽くて速い。Edit/Write は使えないので、変更は加えない。

「ファイルを探す」「コードを横断して検索する」「初見のリポジトリを把握する」といった調査タスクで、Claude が裏で呼び出していることが多い。

Plan

Plan Mode (実践の記事1) 中に、計画を立てる前のコンテキスト収集に使われる。これも読み取り専用で、Claude が現状を理解するためだけに走る。

つまり Plan Mode を使った時点で、こちらは無意識のうちに Plan サブエージェントの恩恵を受けている。

general-purpose

探索と変更の両方が必要な、複雑なマルチステップタスク向け。フルツール権限で動く。「これを調査して、それに基づいて修正して」のような自己完結タスクをまとめて任せる時に使う。

呼び出し方

呼び出し方には三つのレベルがある。

自動委譲 (デフォルト)

何も指定しなくても、Claude が「これはサブエージェントに任せた方が効率的だ」と判断すれば自動的に委譲する。すでに使っているのに気づいていないかもしれない、というのはこのケース。

明示的に頼む

「サブエージェントを使って X を調べて」と指示すれば、Claude は基本的にそれに従う。

サブエージェントを使って、認証システムがトークン更新をどう処理しているか、
既存に再利用できる OAuth ユーティリティがないかを調査して。

調査結果のサマリーだけがメインに返るので、こちらの会話の見通しを保ったまま、認証周りの土地勘を一気に得られる。

@ でサブエージェントを名指し

@ を打つとサブエージェントの候補も出てくる。@code-reviewer (agent) のように選ぶと、そのサブエージェントが必ず使われることが保証される (Claude の判断に委ねない)。

@"code-reviewer (agent)" 認証周りの最近の変更をレビューして

これは特に「Claude が自動委譲してくれない場合」「特定のサブエージェントを必ず使いたい場合」に有効である。

効くパターン

大量読み込みを分離する

最も効果が大きい使い方。「テストスイートを走らせて失敗だけ報告して」「ログファイルを調べてエラーを抽出して」のような、大きな出力を生む操作をサブエージェントに渡す。詳細はサブエージェント側に留まり、メインには要約だけが届く。

サブエージェントを使ってテストを実行して、失敗したテストとエラーメッセージだけ報告して。

並行で複数を調べる

互いに独立した調査は、複数のサブエージェントに並行して走らせられる。

認証、データベース、API の各モジュールを別々のサブエージェントで並行に調査して、
それぞれの主要パターンをまとめて。

それぞれが独立にコードベースを探索して、Claude がメインで結果を統合する。順次に走らせるより速いし、メインのコンテキストも汚れない。

チェーンする

順序立てて使う。「調査結果を踏まえて修正」のようなマルチフェーズタスクで効く。

code-reviewer サブエージェントでパフォーマンス問題を見つけて、
そのあと別のサブエージェントで修正して。

各サブエージェントは結果を Claude に返し、Claude が次のサブエージェントに必要なコンテキストだけを渡す。これも、メイン会話に詳細が積まれない設計である。

メインで進めるか、サブエージェントに渡すか

迷う時の判断軸:

メイン会話サブエージェント
反復・頻繁な対話向く向かない (毎回新規起動)
複数フェーズで文脈共有向く (計画→実装→テスト)各フェーズが独立なら逆
迅速・小タスク向くオーバーヘッド過剰
大量出力を伴うコンテキストが埋まるこれに最も向く
自己完結・サマリーで OK過剰向く

**「メインに残す価値があるか」**が一番素直な問い。残しても判断に効かないなら、サブエージェントに送る。

この先に広がる仕組み

呼び出すだけならここまでで使える。さらに踏み込みたい場合の方向は二つある。

  • 自分専用のサブエージェントを定義する ─ プロジェクト固有のレビュアー、デバッガー、データ分析役などをカスタムで作る。これは応用 (Liber IV) で扱う
  • 複数のサブエージェントを互いに通信させながら動かす ─ 単独タスクではなく、議論や相互検証が必要な並列作業。これにはサブエージェントを超えた Agent Teams という仕組みがある。詳しくはフロンティア (Liber V) で扱う

ここまで実践 (Liber III) の八つの記事を通じて、計画的な進め方、検証、深いレビュー、失敗からの回復、そして委譲を見てきた。日々の作業で Claude Code を相棒として大きな仕事に向かう作法は、これでひと通り揃ったはずである。

次の応用 (Liber IV) では、それらの作法を支えるカスタマイズ機構 ── Skills、Subagents、MCP、Hooks など、Claude Code を自分の環境に組み上げる仕組みを扱う。

参考情報