Claude Codeのサブエージェントとは？使い方・作り方・設定項目まで解説

「Claude Codeに長い調査をさせたら、会話がファイルの中身で埋まってしまった」「レビューだけを専門にやってくれる役を作りたい」と感じている方も多いのではないでしょうか。そうした場面で使うのが、サブエージェントです。

サブエージェントは、メインの会話とは別の作業スペースで、特定の仕事だけを引き受けるClaudeです。調べものやテストの実行など、途中の出力が長くなる作業を任せると、メインの会話には結果の要約だけが返ってきます。役割ごとに使える道具や権限を絞った「専門担当」を、自分で作ることもできます。

この記事では、サブエージェントの仕組みから、最初から入っているサブエージェント、呼び出し方、自分で作る手順、設定項目の使い分け、費用と注意点、うまく動かないときの対処までを順に解説します。内容は2026年10月時点の公式ドキュメントをもとにしています。Claude Codeは更新が頻繁なので、使う前に公式ドキュメントもあわせて確認してください。

サブエージェントとは

サブエージェントは、Anthropic社のプログラミング用AI「Claude Code」の中で動く、専用の助手のようなものです。公式ドキュメントでは「特定の種類の仕事を引き受ける、専門のAIアシスタント」と説明されています。

ふつうのClaude Codeは、1つの会話の中で、読んだファイルも実行した結果もすべて同じ画面に積み重ねていきます。すると会話が長くなり、あとから別の作業をするときにも、その内容を引きずることになります。サブエージェントを使うと、調べもののような「途中経過が多い作業」を別の作業スペースに切り出し、結論だけをメインの会話に持ち帰ることができます。

人の仕事にたとえると、課長が部下に「この3つの資料を読んで、要点を5行でまとめて」と頼み、資料そのものは見ずに要点だけ受け取る形に近いものです。課長（メインの会話）の机は散らかりません。

各サブエージェントには、次の3つが個別に用意されています。

• 専用の作業スペース（コンテキストウィンドウ。Claudeが一度に覚えておける作業メモの範囲）
• 専用の指示（役割・手順・出力の形式を書いたもの）
• 使える道具と権限（ファイルを読むだけ、書き換えてよい、など）

どのサブエージェントに任せるかは、Claudeが各サブエージェントの「説明（description）」を読んで判断します。説明に合う仕事が来ると、自動でそのサブエージェントに渡されます。

何が助かるのか

公式ドキュメントでは、サブエージェントの利点が5つ挙げられています。業務に置き換えると、次のようになります。

他の「並列で動かす仕組み」との違い

Claude Codeには、複数の作業を同時に進める方法が、サブエージェントのほかにもあります。公式ドキュメント「Run agents in parallel」では5つの方法が比べられています。名前が似ているので、違いを表にまとめました。

サブエージェントは、このうちいちばん基本の部品です。ほかの仕組みの多くも、中身はClaudeのセッションやサブエージェントの組み合わせでできています。まずサブエージェントを理解しておくと、Agent Teamsなどの理解も早くなります。

サブエージェントとAgent Teamsの大きな違いは、連絡の仕方です。サブエージェントは結果を呼び出し元に返すだけで、リーダーがすべての作業を管理します。Agent Teamsでは、メンバー同士が直接メッセージを送り合い、共有のタスクリストで自分たちで進めます。そのぶんAgent Teamsは使用量も多くなります。詳しくは次の記事で解説しています。

メインの会話で進める場面・サブエージェントに任せる場面

何でもサブエージェントに任せればよいわけではありません。公式ドキュメントは、使い分けの目安を次のように示しています。

公式ドキュメントには、ほかにも2つの案内があります。ひとつは、毎回使い回したい手順やプロンプトなら、サブエージェントではなくスキルの方が合うという点です。スキルは、メインの会話の中で実行される手順書です。もうひとつは、会話の中にすでにある内容についての質問なら、/btwというコマンドを使う方法です。こちらはサブエージェントを起こさず、会話の全体を見ながら答え、答えは履歴に残りません。

標準のサブエージェント

Claude Codeには、最初から入っているサブエージェントがいくつかあります。何も設定しなくても、Claudeが必要だと判断したときに自動で使います。使う人が呼び出さなくてもよいものが多いので、「裏でこういう助手が動いている」と知っておくだけでも、画面の表示が理解しやすくなります。

いずれも、メインの会話の権限のルールを引き継ぎます。標準のサブエージェントだからといって、許可していない操作ができるようになるわけではありません。

ExploreとPlanは軽く動く

ExploreとPlanは、調べものを速く、軽く済ませるために、CLAUDE.mdとGitの状態の情報を持たずに起動します。ほかのサブエージェントは、どちらも読み込んだ状態で始まります。

Exploreに任せるとき、Claudeは調べる深さを3段階から選びます。ピンポイントの確認なら「quick」、バランス重視なら「medium」、徹底的な調査なら「very thorough」です。

使うモデルにも決まりがあります。Exploreは、基本的にメインの会話と同じモデルで動きます。ただし、メインの会話がFableモデルのときは、Claudeの契約・Anthropic Consoleのアカウント・LLMゲートウェイ経由なら、Exploreはopusのエイリアス（別名）が指すOpusモデルで動きます。Amazon Bedrockなどのクラウド経由では、メインの会話のモデルのままです。

標準のサブエージェントを止めたいとき

標準のサブエージェントは、次の方法で止められます。ふだんは触る必要はありませんが、会社の方針で「自動で別の助手を起こしたくない」という場合に使えます。

なお、v2.1.63で「Task」というツールの名前が「Agent」に変わりました。古い記事で「Taskツール」と書かれているものは、いまのAgentツールのことです。設定ファイルに古い Task(...) の書き方が残っていても、別名として動きます。

使い方

サブエージェントの呼び出し方は、公式ドキュメントでは「自動」「名前で頼む」「@メンション」「セッション全体を切り替える」の4段階に整理されています。順に説明します。

自動で任せる

何も指定しなくても、Claudeは依頼の内容と各サブエージェントの説明を見て、合うものに仕事を任せます。ふだんの使い方はこれで十分です。

自作のサブエージェントを、Claudeにもっと積極的に使わせたいときは、説明（description）に「use proactively（積極的に使う）」のような一言を入れておきます。説明が具体的であるほど、Claudeは迷わず選べます。

名前で頼む

特別な書き方は要りません。サブエージェントの名前を、依頼文の中で書きます。

test-runnerサブエージェントを使って、失敗しているテストを直して
code-reviewerサブエージェントに、直近の変更を見てもらって

この場合、実際に任せるかどうかはClaudeが判断します。

@メンションで確実に呼ぶ

入力欄で「@」を打つと、サブエージェントの一覧が表示されます。ファイルを指定するときと同じ操作です。@で選んだサブエージェントは、確実に使われます。

@"code-reviewer (agent)" 認証まわりの変更を見て

@メンションで決まるのは「どのサブエージェントを呼ぶか」だけです。サブエージェントへの依頼文は、入力した内容をもとにClaudeが書きます。

セッション全体をサブエージェントとして動かす

起動するときに --agent を付けると、メインの会話そのものが、そのサブエージェントの道具の制限とモデルで動きます。

claude --agent code-reviewer

自作のサブエージェントの指示は、通常のClaude Codeの指示を置き換えます。CLAUDE.mdやプロジェクトのメモリは、これまでどおり読み込まれます。毎回このサブエージェントで始めたい場合は、プロジェクトの .claude/settings.json に "agent": "code-reviewer" と書いておきます。コマンドの --agent と設定が両方あるときは、コマンドが優先されます。

前面で動かすか、背景で動かすか

サブエージェントには、前面（フォアグラウンド）で動かす方法と、背景（バックグラウンド）で動かす方法があります。

公式ドキュメントによると、対話モードではフォーク機能（後述）が初期設定で有効で、Claudeが起こすサブエージェントは基本的に背景で動きます。実行中のタスクを背景に回したいときは、Ctrl+Bを押します。背景で動くサブエージェントは、前面のものより使える道具が少し絞られます。ファイルの読み書きやWeb検索などの主な道具は使えます。

背景で動くサブエージェントの結果は、完了の通知として、あとのやりとりでClaudeに届きます。途中で「どうなった？」と聞くと、まだ実行中だと答えます。

進み具合を見る・止める・再開する

サブエージェントが動いている間は、入力欄の下に一覧のパネルが表示されます。/tasksコマンドでも、背景で動いている作業を一覧できます。完了したサブエージェントも、30秒間は一覧に残ります。

ひとつ注意があります。サブエージェントを呼び出すたびに、新しい別の助手が起動します。前回の作業を引き継がせたいときは、「続きから」と伝えて、再開（resume）させます。再開したサブエージェントは、それまでの会話・実行した操作・結果をすべて覚えた状態で続きを始めます。

ただし、標準のExploreとPlanは1回で終わる設計のため、再開できません。続けたい場合は、general-purposeか、自作のサブエージェントを使います。

サブエージェントの記録は、パソコンの ~/.claude/projects/ 以下に保存され、初期設定では30日で削除されます。WindowsではこのフォルダはC:\Users\ユーザー名の中の .claude にあたります。

会話ごと引き継ぐ「フォーク」

通常のサブエージェントは、メインの会話の履歴を見ずに、まっさらな状態で始まります。一方、フォークは、これまでの会話の全体を引き継いで始まるサブエージェントです。背景の説明を一から書かなくてよいので、「ここまでの実装を前提に、テストの案だけ並行して書いて」のような頼み方に向いています。

フォークを自分で起動するには、/subtaskのあとに作業内容を書きます（v2.1.212以降）。

/subtask ここまでのパーサーの変更に対する単体テストの案を書いて

フォークは、さらにフォークを起こすことはできません。なお、/forkは別のコマンドで、会話全体を新しい背景セッションにコピーします（エージェントビューを無効にしている場合は、/forkがフォークの起動コマンドになります）。

自分で作る

サブエージェントは、Markdown形式の1つのファイルでできています。ファイルの先頭にYAML形式の設定（フロントマター）、その下に指示を書く形です。専用の画面は要りません。Claudeに頼めば、ファイルごと書いてもらえます。

作る手順

公式ドキュメントのクイックスタートをもとに、個人用のコードレビュー担当を作る流れを紹介します。

1. Claudeに作りたい内容を頼むどこに保存するかも含めて、日本語で依頼します。たとえば「~/.claude/agents/ に、コードの読みやすさや性能の改善点を指摘する code-improver というサブエージェントを作って。読み取り専用で、Sonnetを使って」と伝えます。
2. できたファイルを確認するClaudeは、名前・説明・使える道具・モデル・指示を書いたファイルを作ります。内容が希望どおりかを確認します。
3. 試しに呼び出す「code-improverサブエージェントを使って、このプロジェクトの改善点を挙げて」のように頼みます。画面には、サブエージェントの名前と作業の概要が表示されます。
4. 足りない点を直す指示が曖昧で意図とずれるときは、ファイルの指示を書き足します。説明（description）を具体的にすると、自動で呼ばれる精度も上がります。

ファイルの形

公式ドキュメントにあるコードレビュー担当の例です。---で囲まれた部分が設定、その下が指示です。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

必須なのはname（名前）とdescription（いつ使うかの説明）の2つだけです。ほかの項目は、必要に応じて足していきます。指示の本文は日本語でも書けます。

サブエージェントの指示として渡されるのは、この本文と、作業フォルダなどの基本的な環境情報です。Claude Code本体の指示は渡されません。CLAUDE.mdなどは別に読み込まれます（詳しくは「活用例」の最後で説明します）。

置き場所と優先順位

ファイルの置き場所で、誰が使えるかが決まります。同じ名前のものが複数あるときは、優先順位の高い方が使われます。

Windowsでは、~/.claudeは %USERPROFILE%\.claude（C:\Users\ユーザー名\.claude）にあたります。

使い分けの目安は次のとおりです。

• プロジェクト用（.claude/agents/）：そのプロジェクト専用の担当。Gitで管理すれば、チームで共有して改善できる
• 個人用（~/.claude/agents/）：自分用の担当。どの案件でも使いたいレビュー担当など

フォルダの中は、サブフォルダに分けて整理できます（例：agents/review/）。サブフォルダの名前は、呼び出し方に影響しません。サブエージェントを区別するのは、ファイル内のnameだけです。同じフォルダの下に同じnameのファイルが2つあると、片方しか読み込まれません。どちらが使われるかも決まっていないので、名前は重複させないでください。

その場だけの定義（--agents）

ファイルを残さず、そのセッションだけで使う方法もあります。起動時に、JSONで定義を渡します。試しに使うときや、自動化のスクリプトに向いています。Windows（PowerShell）では、次のように書きます。

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}
'@

JSONのpromptが、ファイルの本文にあたります。-p（非対話モード）では、定義が長いときにJSONファイルのパスを渡すこともできます（v2.1.281以降）。

ファイルが読み込まれない条件

次のどれかに当てはまると、Claude Codeは画面に何も表示せずに、そのファイルをとばします。作ったのに使われないときは、ここを確認してください。

• nameがない（解説用の文書として扱われる）
• 最初の---が、ファイルの1行目にない
• nameが-で始まる、:を含む、または256字を超える
• nameはあるが、descriptionがない
• YAMLの書き方が正しくない

理由は、claude --debugで起動したときのデバッグログに出ます。フロントマターの項目名を書き間違えていても、エラーにはならず、無視されます。項目名は大文字・小文字も含めて、正確に書いてください（例：maxTurns、disallowedTools）。

設定の選び方

フロントマターには、役割に合わせて調整できる項目がいくつかあります。まず全体を表で確認し、そのあとで主なものを順に説明します。

使える道具を絞る

最もよく使うのが、道具の制限です。toolsには使ってよいものを並べ、disallowedToolsには使わせないものを並べます。

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

この例では、ファイルの読み取り・検索と、コマンドの実行だけができます。ファイルの書き換えやMCPのツールは使えません。

反対に、「書き換え以外は引き継ぐ」なら、次のように書きます。

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

両方を書いた場合は、disallowedToolsが先に適用され、残ったものの中からtoolsが決まります。両方に書かれた道具は、使えません。

なお、どの設定を書いても、次のツールはサブエージェントから外されます。ユーザーに質問を投げるAskUserQuestion、プランモードの出入りのEnterPlanMode・ExitPlanMode（権限モードがplanの場合を除く）などです。

モデルを選ぶ

modelで、サブエージェントごとにモデルを変えられます。実際に使われるモデルは、次の順番で決まります。

すべてのサブエージェントを1つのモデルにそろえたいときは、CLAUDE_CODE_SUBAGENT_MODELに加えてCLAUDE_CODE_SUBAGENT_MODEL_FORCEを1にします（v2.1.257以降）。設定ファイルのenvに書く形です。

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

この強制設定をオンにすると、定義のmodelは無視されます。役割ごとにモデルを分けたい場合には使わないでください。

また、サブエージェントの作業スペースの大きさは、そのサブエージェントのモデルで決まります。メインより小さいモデルに任せると、作業スペースも小さくなります。考える深さ（拡張思考）の設定は、メインの会話のものを引き継ぎます。

権限モードを選ぶ

permissionModeで、サブエージェントが「どこまで確認なしに動くか」を決めます。ただし、メインの会話のモードによっては、指定が無視されます。

値にはdefault（確認を求める）、acceptEdits（ファイルの編集を自動で許可）、auto（自動モード）、dontAsk（確認が必要な操作を自動で拒否）、plan（読み取り専用の探索）などがあります。迷ったら、書かずにメインを引き継ぐのが安全です。

スキルとメモリを持たせる

skillsにスキルの名前を並べると、サブエージェントの起動時に、その内容がまるごと読み込まれます。「この案件のコーディングルールに従って書く」のように、前提知識を最初から持たせたいときに使います。

memoryを指定すると、サブエージェント専用の記憶フォルダが用意され、会話をまたいで学んだことを覚えていきます。範囲は3つです。

公式ドキュメントでは、projectが推奨の初期値とされています。メモリを有効にすると、ファイルの読み書きの道具も自動で使えるようになります。自動メモリ（auto memory）をオフにしている場合は、この項目は効きません。

フックで細かく制御する

道具の制限だけでは足りないときは、フックを使います。たとえば「データベースは読めるが、書き込みの命令（INSERT・UPDATE・DELETEなど）は実行させない」といった条件付きの制御です。PreToolUseというフックで、コマンドの実行前に中身を調べ、終了コード2を返すと、その操作が止められます。

フックの詳しい書き方は、公式ドキュメントの「Hooks」のページで確認できます。Windowsでは、フックのスクリプトをPowerShellで書き、フックの設定にshell: powershellを加えます。

また、設定ファイル側にはSubagentStartとSubagentStopというイベントがあり、サブエージェントの開始・終了のときに処理を動かせます。名前（matcher）で対象を絞ることもできます。

別のコピーで安全に動かす

isolation: worktreeを指定すると、サブエージェントは、リポジトリの一時的な別コピー（Gitのワークツリー）で動きます。メインの作業フォルダのファイルを直接書き換えないので、「試しに大きく直させる」ような作業でも、手元のファイルを汚しません。サブエージェントが何も変更しなければ、コピーは自動で片づけられます。

入れ子と同時実行の上限

サブエージェントは、条件によっては、別のサブエージェントを起こすこともできます。公式ドキュメントでは、次の既定値が示されています。

入れ子の深さの限度まで来たサブエージェントは、Agentツールが外され、自分で作業して要約を1つ返します。特定のサブエージェントが、ほかのサブエージェントを起こさないようにするには、toolsからAgentを外すか、disallowedToolsに入れます。

活用例

サブエージェントは、「途中の出力が多い」「読むだけでよい」「役割が決まっている」という仕事と相性がよい機能です。使い方の例を、場面ごとに整理しました。

依頼文の例

公式ドキュメントに載っている、代表的な頼み方です。日本語でも同じように使えます。

出力の多い作業を切り出す

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

並行して調べる

認証・データベース・APIの3つのモジュールについて、別々のサブエージェントで並行して調べてください。

それぞれが自分の担当を調べ、最後にClaudeが結果をまとめます。調べる先が互いに依存していないときにうまくいきます。

順番につなぐ

code-reviewerサブエージェントで性能の問題を見つけて、そのあとoptimizerサブエージェントで直してください。

各サブエージェントの結果はClaudeに戻り、Claudeが次のサブエージェントに必要な情報を渡します。

定義の例：読み取り専用のレビュー担当

公式ドキュメントのコードレビュー担当の例を、日本語の指示にした形です。書き換えの道具（EditとWrite）を外し、「確認だけ」に役割を絞っています。

---
name: code-reviewer
description: コードの品質・安全性・保守しやすさを確認するレビュー担当。コードを書いた・変更した直後に使う
tools: Read, Grep, Glob, Bash
model: inherit
---

あなたは品質と安全性を重視するコードレビュー担当です。

呼び出されたら、次の順で進めてください。
1. git diff で直近の変更を確認する
2. 変更されたファイルに絞って見る
3. すぐにレビューを始める

確認の観点：
- 読みやすく、名前が適切か
- 同じ処理の重複がないか
- エラーの扱いが適切か
- パスワードやAPIキーが書かれていないか
- 入力値の確認があるか

結果は、重要度の順（必ず直す・直した方がよい・提案）で報告してください。
直し方の具体例も添えてください。

ポイントは3つあります。役割を1つに絞ること、説明（description）に「いつ使うか」を書くこと、道具は必要なものだけにすることです。公式ドキュメントも、同じ点を推奨しています。

非エンジニアの方の使い方の例

プログラムを書かない仕事でも、使える場面はあります。Claude Codeでサイトの文章や設定ファイルを扱っている方なら、次のような担当を作ると便利です。

• 文章のチェック担当：読み取り専用にして、誤字・表記ゆれ・言い回しの確認だけをさせる。原稿を書き換えられる心配がない
• 資料の要点整理担当：長い資料のフォルダを読み込ませ、要点だけを返させる。元の資料の内容が会話を圧迫しない
• 変更内容の確認担当：自分が直したファイルの変更点を、読み取り専用で点検させる

どれも、はじめは「読み取り専用」から始めるのがおすすめです。書き換えの道具を渡さなければ、間違った指示で大事なファイルを変えられる心配がなくなります。

依頼文に書くこと

サブエージェントは、メインの会話の履歴を見ません。受け取るのは、Claudeが書いた依頼文と、CLAUDE.md・Gitの状態などです。そのため、メインの会話で話し合った前提は、サブエージェントには伝わっていないと考えてください。

メインのCLAUDE.mdにある決まりごとのうち、サブエージェントにも必ず守らせたいもの（例：「vendor/フォルダは見ない」）は、依頼するときの文章に書き直して伝えます。

費用・注意点・困ったとき

使用量はサブエージェントの分も増える

サブエージェントは、メインの会話の「内側」で動きますが、それぞれが自分でAIへのリクエストを送ります。その分は、メインの会話と同じ使用量の上限に数えられます。公式ドキュメントでも、メインの会話の使用量とは別に、サブエージェントやワークフローのリクエストが加わると説明されています。

サブエージェントに任せると、メインの会話の文脈は軽くなります。ただし、使用量全体が減るとは限りません。「便利だから何でも任せる」と、気づかないうちに使用量が増える場合があります。

プランごとの料金や使用量の上限については、料金の記事もあわせて確認してください。

結果が返ってきたときの注意

サブエージェントの結果は、メインの会話に戻ります。公式ドキュメントも、詳しい結果を返すサブエージェントを大量に走らせると、メインの会話の文脈をかなり使うと注意しています。「要点を5行で」「失敗したものだけ」のように、返してほしい量を依頼文で指定しておくと、メインの会話が重くなりません。

さらに、並行して動かしたい作業が多い、あるいは1つの文脈に収まらない規模の場合は、サブエージェントではなく、別々のセッションに分けるのが適しています。

権限と安全

サブエージェントは、メインの会話の権限のルールを引き継ぎます。そのうえで、次の点に気をつけてください。

• 道具は最小限にする：読むだけでよい役割なら、書き換えの道具は渡さない。公式ドキュメントも「必要な権限だけを渡す」ことを勧めています
• 背景で動くものも確認が出る：許可の確認は、メインの会話に表示されます。「このセッションの間は許可」のように、あとまで続く許可を選ぶと、メインの会話を含むセッション全体に適用されます
• サブエージェントが読んだ内容には、指示のような文が混じることがある：Claude Codeは、サブエージェントの最終報告を読む前にスキャンし、Claude Codeの出力を装った文などに印を付けます（v2.1.210以降）。ただし、これは悪意の有無を判断するものではありません。権限の確認そのものは、通常どおり働きます
• ほかのエージェントからのメッセージは、承認にならない：公式ドキュメントでは、どのエージェントからのメッセージも「ユーザーの承認」とは見なされず、サブエージェントの権限設定やCLAUDE.mdを変えることもできないと明記されています

うまく動かないとき

よくある症状と、確認する点を表にまとめました。

よくある質問

まとめ

サブエージェントは、「何を任せ、何を手元に残すか」を決めると効果が出る機能です。まずは標準のExploreやPlanがどう動いているかを/tasksで眺め、次に読み取り専用のレビュー担当を1つ作ってみるのが、取りかかりやすい順番です。

社内でClaude Codeを使う場面では、サブエージェントの置き場所、権限の決め方、使用量の管理など、先に決めておくことが増えていきます。INTERCREATE JAPANでは、Claude Codeの導入から、社内で使い続けられる設定やルールづくりまでをお手伝いしています。