Claude Code のサブエージェントの使い方
Claude Code の サブエージェント は、メインの会話とは 別のコンテキスト で動く、補助の AI アシスタントです。重い調べ物や探索を、メインのやりとりから切り離して任せられます。
この記事では、サブエージェントが何なのか、なぜ便利なのか、組み込みのものと自作のものをどう使うかを、個人開発者向けに整理します。対象は Claude Code v2.1.148 時点。組み込みスキルやスラッシュコマンドの一覧は、別記事（組み込みスキル 10 個／スラッシュコマンド 30 個）にまとめています。
サブエージェントとは何か
ふつう、Claude Code との会話は 1 本の流れです。やりとりが進むほど、会話の文脈（コンテキスト）には、検索結果やファイルの中身がたまっていきます。長い調査をすると、本来やりたかった作業の前に、文脈が雑多な情報で埋まってしまう。
サブエージェントは、これを避ける仕組みです。特徴は、次の 3 つ。
- コンテキストが分離している … サブエージェントはメインの会話履歴を見ません。渡された「依頼」だけを受け取って動きます。
- 結果の要約だけが戻る … 大量のログやファイルを読んでも、メインの会話に戻ってくるのは結論だけ。メインの文脈は汚れません。
- 役割を絞れる … 使えるツールやふるまいを限定できます。「検索だけさせる」といった制限が可能です。
たとえば「コードベース全体から、ある関数の使われ方を洗い出す」作業。メインで直接やると検索結果が大量に残りますが、サブエージェントに任せれば、戻ってくるのは「どこで何回、こう使われている」という要約だけです。
組み込みのエージェント
Claude Code には、最初から使えるエージェントがあります。主なものは次のとおり。
| エージェント | 性質 | 用途 |
|---|---|---|
Explore | 読み取り専用・軽量 | コードやファイルの探索・検索 |
Plan | 読み取り専用 | 実装方針を立てるための調査 |
general-purpose | すべてのツールを使える | 調査から修正まで含む複雑な作業 |
このほか、Claude Code 自体への質問に答える claude-code-guide、ステータスライン設定用の statusline-setup などがあります。「コードベースを調べて」と頼めば、Claude は適切な組み込みエージェントを選んで動かします。
カスタムエージェントを作る
同じ種類の作業を何度も頼むなら、自分用のエージェントを定義しておけます。.claude/agents/ に Markdown ファイルを置くだけです。
---
name: code-reviewer
description: コードの品質とベストプラクティスをレビューする。レビューを頼まれたら使う。
tools: Read, Glob, Grep
model: sonnet
---
あなたはコードレビュアーです。変更されたコードを読み、品質・
セキュリティ・可読性の観点から、具体的で実行可能な指摘を返してください。- frontmatter の
nameとdescriptionは必須です。descriptionには「いつこのエージェントに任せるか」を書きます ── Claude はこれを読んで、使うかどうかを判断します。 tools… 使わせるツールを限定します（省略すると全部継承）。上の例は読み取り系だけに絞っています。model…haiku/sonnet/opusなど。軽い作業なら、安いモデルを指定できます。- frontmatter の下の本文が、そのエージェントへの指示（システムプロンプト）になります。
ファイルの置き場所は 2 通り。プロジェクト直下の .claude/agents/ はそのプロジェクト専用、ホームの ~/.claude/agents/ は全プロジェクト共通です。このほか、実行ターン数の上限など、ふるまいを細かく決めるフィールドもあります。
呼び出し方
作ったエージェントは、3 通りで呼べます。
- 自然言語で頼む …「code-reviewer エージェントでこの変更をレビューして」。Claude が判断して任せます。
- 明示的に指名する …
@でエージェントを名指しすると、必ずそのエージェントが動きます。 - セッションごと指定する …
claude --agent code-reviewerのように起動すると、そのエージェントが主役になります。
複数のサブエージェントを 同時に並列で 走らせることもできます（その分、トークンの消費は増えます）。独立した複数の調査を、まとめて片付けたいときに有効です。
個人開発者が使う場面
- 重い調査を切り出す … ログ解析、影響範囲の洗い出し、ドキュメントの横断検索。メインの文脈を守りたいとき。
- 役割を絞って安全にする … 「検索だけ」「読み取りだけ」のエージェントに、調べ物を任せる。
- 同じ作業を定型化する … レビュー、テスト実行など、繰り返す作業をカスタムエージェントにしておく。
まとめ
サブエージェントの本質は、コンテキストの分離 です。重く雑多な作業を別の場所へ追い出し、メインの会話を、本来の目的のためにきれいなまま保つ。まずは「コードベースを調べて」と頼んで、組み込みの Explore が動くのを眺めるところから。繰り返す作業が見えてきたら、.claude/agents/ に 1 つ、自分用のエージェントを置いてみましょう。
サブエージェントには、開始・終了のタイミングでフックを仕掛けることもできます。フックの仕組みは、別記事 Claude Code の hooks でできること にまとめています。