この記事でわかること

  • Claude Codeのサブエージェントが何をするもので、どんな作業に向くか
  • 最初から用意されているサブエージェントと、その注意点
  • 調べものやテストの実行を任せるときの頼み方
  • 自分用のサブエージェントを作るときの書き方と置き場所
  • 返ってきた報告の確かめ方

先に結論を書くと、サブエージェントに向くのは、出力が多く、結果を短くまとめて返せる、ひとまとまりの作業です。返ってくるのは要約なので、作業の判断に使う事実は、自分で元の資料やファイルを開いて確かめます。

基本的な使い方はClaude Codeの始め方と使い方、長い作業の区切り方はClaude Codeで長期プロジェクトを進める方法で扱っています。この記事の仕組みの説明は、Claude Codeの公式ドキュメント「Create custom subagents」で2026年10月20日に確かめた内容です。

サブエージェントとは

サブエージェントは、特定の種類の作業を受け持つ、専用のAIアシスタントです。メインの会話とは別の、自分のコンテキスト(会話の記憶の枠)で作業し、終わると要約だけを返します。

たとえば、テストを全件実行したり、長いログを読んだりすると、出力が会話に大量に残ります。これをサブエージェントに任せると、長い出力はサブエージェントの側に残り、メインの会話には必要な要約だけが戻ります。

注意したいのは、サブエージェントも自分でリクエストを送り、その分はメインの会話と同じ利用上限に数えられることです。会話は軽くなっても、使う量が減るわけではありません。

どのサブエージェントに任せるかは、頼まれた作業の内容と、それぞれのサブエージェントの説明(description)をもとに、Claude Codeが決めます。

最初から用意されているサブエージェント

自分で作らなくても、Claude Codeには最初からいくつかのサブエージェントがあり、必要に応じて使われます。

  • Explore: コードベースの検索と分析のための、読み取り専用のサブエージェント
  • Plan: プランモードで、計画を示す前に情報を集めるサブエージェント(読み取り専用)
  • general-purpose: 調べものと変更の両方が必要な、複数の手順の作業を受け持つサブエージェント

ここで気をつけたいのは、Explore と Plan は、CLAUDE.md を読まずに始まることです。調べものを速く安く済ませるための設計ですが、触ってはいけないフォルダや秘密の情報の扱いなどを CLAUDE.md に書いていても、それは伝わりません。守ってほしい条件は、頼む文の中に書きます。CLAUDE.md に何を書くかはCLAUDE.mdの書き方にまとめています。

任せる作業と任せない作業

公式ドキュメントは、サブエージェントに向く作業として、出力が多くメインの会話に残す必要がないもの、使うツールや権限を絞りたいもの、ひとまとまりで要約を返せるものを挙げています。反対に、何度もやりとりして直していく作業、計画・実装・テストのように段階の間で多くの前提を共有する作業、小さな修正は、メインの会話が向くとしています。

作業の例 向く先
全件テスト 任せる
ログの調査 任せる
資料の調べもの 任せる
設計の相談 会話
小さな修正 会話
続けて行う変更 会話

表の「会話」は、メインの会話で頼むことを指します。サブエージェントは毎回まっさらな状態から始まるため、前提を集めるのに時間がかかることがあります。すぐ終わる作業は、メインの会話で頼んだほうが早く済みます。

長いログを読ませる作業で、渡してよい情報と結果の確かめ方はApacheのログ解析をAI(Claude Code)に任せる方法で紹介しています。

任せるときの頼み方

使ってほしいサブエージェントの名前を書いて頼むと、任せるかどうかをClaude Codeが判断します。必ず特定のサブエージェントに任せたいときは、@ を入力して一覧から選ぶ方法もあります。

頼む文には、次の4つを書きます。

  • 何をするか: 調べる範囲や、実行するコマンド
  • 何を返すか: 報告の形(失敗したテストの名前だけ、など)
  • してはいけないこと: ファイルを変更しない、など
  • 根拠の示し方: どのファイルや資料をもとにしたか

テストの実行を任せる例です。

サブエージェントを使って、テストを全件実行してください。
失敗したテストの名前と、エラーの要点だけを報告してください。
ファイルは変更しないでください。

調べものを任せる例です。報告に出典と原文を付けてもらうと、あとで自分で確かめやすくなります。

サブエージェントを使って、Claude Code の公式ドキュメントで、
サブエージェントの定義ファイルの置き場所を調べてください。
見つけた内容ごとに、ページのURLと、
根拠になる原文の1文を添えて報告してください。
ファイルは作成も変更もしないでください。

テストを頼むときの考え方はClaude Codeにテストを書かせる方法で紹介しています。

自分用のサブエージェントを作る

同じ指示で同じ種類の作業を何度も頼むなら、自分用のサブエージェントを定義しておくと便利です。サブエージェントは、YAMLのフロントマター(先頭の設定の部分)が付いた Markdown のファイルです。Claude Codeに「こういうサブエージェントを作って」と頼んで、ファイルを書いてもらうこともできます。

置き場所によって、使える範囲が変わります。

  • .claude/agents/: そのプロジェクトだけで使えます。リポジトリに入れて、チームで共有できます
  • ~/.claude/agents/: 自分のすべてのプロジェクトで使えます

読み取り専用の調査役の例です。

---
name: doc-researcher
description: 公式ドキュメントを調べて、出典つきで報告する。調べものを頼まれたときに使う
tools: Read, Grep, Glob, WebFetch
---

あなたは調査の担当です。ファイルは作成も変更もしません。
見つけた事実ごとに、出典のURLと根拠の原文を1文添えて報告してください。
確かめられなかったことは「未確認」と書いてください。

この例は公式ドキュメントの書式に合わせたもので、動作を確かめたものではありません。書くときのポイントは次のとおりです。

  • 必須は name と description だけ: description は、Claude Codeが任せるかを決める材料になるため、どんなときに使うかを短く書きます
  • tools で使えるツールを絞る: tools を書かないと、使えるツールをすべて引き継ぎます。読み取りだけの役なら、読み取りのツールだけを書きます
  • 本文が指示になる: ファイルの本文は、そのサブエージェント用の指示になります。サブエージェントが受け取るのはこの指示と作業フォルダなどの基本的な情報で、Claude Code本体の指示は受け取りません

定義ファイルを置くフォルダを、セッションの途中で新しく作った場合は、Claude Codeを起動し直します。起動中のセッションは、新しく作られたフォルダを見つけられません。

返ってきた報告の確かめ方

サブエージェントの報告は要約です。途中で何を読み、何を読まなかったかは、メインの会話からは見えません。そのため、報告をそのまま事実として使わず、次の順で確かめます。

  1. 報告に出てくるファイル名や設定の名前が、実際にあるかを開いて確かめる
  2. 出典のURLがある場合は、そのページを開き、添えられた原文が本当に書かれているかを見る
  3. 「すべて確認した」「問題なし」のような結論は、何を確かめた結果なのかを聞き返す
  4. 作業の判断に使う事実だけは、自分で元の資料を読み直す

このサイトの記事づくりでも、事実をまとめる台帳の決まりとして、調査用のサブエージェントの報告は参考にとどめ、記事で使う時点によって変わる事実は、自分で公式ページを開いて確かめてから使うことにしています。この記事の仕組みの説明も、公式ドキュメントの原文を取得し、引用が一字一句一致することを確かめてから書きました。

AIの出力を確かめる手順そのものは、AIの出力をどう確認するかで詳しく紹介しています。

並べて任せるときの注意

互いに関係しない調べものは、複数のサブエージェントに同時に任せられます。公式ドキュメントは、調べる道筋どうしが依存しないときに最もうまくいくとしています。

一方で、それぞれの結果はメインの会話に戻ってきます。詳しい報告を返すサブエージェントをたくさん動かすと、メインの会話のコンテキストを大きく使い、サブエージェントもそれぞれ自分の分を使います。並べて任せるときほど、報告は短く、必要な項目だけを返すように頼みます。

前の結果を使って次の作業をする場合は、同時ではなく、順番に任せます。1つ目の結果をClaude Codeが受け取り、必要な部分を次のサブエージェントに渡す形です。

つまずきやすいところ

  • 使う量が減ると思い込む: サブエージェントの分も、同じ利用上限に数えられます
  • CLAUDE.md のルールが伝わっている前提で任せる: Explore と Plan は CLAUDE.md を読まずに始まります。条件は頼む文に書きます
  • tools を書かずに調査役を作る: 書かないと、使えるツールをすべて引き継ぎます
  • 要約を確かめずに使う: ファイル名・出典・原文を、自分で開いて確かめます
  • 小さな修正まで任せる: まっさらな状態から始まるぶん、かえって時間がかかることがあります

まとめ

  • サブエージェントは自分のコンテキストで作業し、要約だけを返します。使う量そのものは減りません
  • 向くのは、出力が多く、ひとまとまりで要約を返せる作業です。やりとりが多い作業や小さな修正は、メインの会話で頼みます
  • 頼む文には、何をするか・何を返すか・してはいけないこと・根拠の示し方を書きます
  • 自分用のサブエージェントは、name と description が必須で、tools で使えるツールを絞ります
  • 返ってきた報告は、ファイル名・出典・原文を自分で開いて確かめてから使います