Claude Codeに大きなリポジトリの調査を頼んだら、検索結果やログでメインの会話が埋め尽くされてしまった、という経験はないでしょうか。その状態が続くと、本当に必要な指示や過去のやり取りが会話の奥に埋もれていき、Claudeが文脈を見失いやすくなります。この「会話が重くなる問題」は、長い調査を任せる場面で起きやすい代表的な悩みです。
この問題に対する公式の答えが、今回扱うサブエージェント(subagents)です。サブエージェントは、Claude Codeが特定の種類のタスクを任せられる、独立した文脈を持つAIアシスタントのことで、Claude Code公式ドキュメントに仕組みと設定方法がまとまっています。
この記事では、公式ドキュメントの記載内容だけを根拠に、サブエージェントで何ができるのか、設定ファイルをどこにどう書けばよいのか、いつ使うべきでいつは避けたほうがよいのかを整理します。Claude Code自体の導入や基本操作は既存の解説記事に譲り、ここではサブエージェントという機能に絞って掘り下げます。動作を確認していない手順については「公式ドキュメントにこう書かれている」という形で提示し、筆者が実行した結果であるかのようには書きません。
この記事でわかること
【完全無料】AI×SNSで成果を出す100大特典を受け取る
AIの使い方を、SNS運用の実務につなげたい方へ。LINEで特典の案内を受け取れます。
サブエージェントの定義と使う狙い、Explore・Plan・general-purposeといったビルトインの種類、.claude/agents/や~/.claude/agents/といった設定ファイルの置き場所と優先順位、YAMLフロントマターの主要フィールド、modelフィールドによるモデル指定の仕組み、toolsとdisallowedToolsによるツール制限、呼び出し方の種類、会話全体を引き継ぐfork機能との違い、そして使うべき場面と使わないほうがよい場面までを順番に扱います。Claude Codeそのものの使い方を先に知りたい方はClaude Code 使い方の解説記事を先に読むと理解が早まります。
Claude Codeの「サブエージェント」とは何か
サブエージェントとは、Claude Codeがメインの会話とは別のコンテキストウィンドウで特定の種類のタスクを処理する、専用のシステムプロンプト・ツールアクセス・権限を持ったAIアシスタントのことです。
公式ドキュメントは、サブエージェントを使う基準を次のように説明しています。副次的なタスクが、検索結果やログ、二度と参照しないファイル内容でメインの会話を埋めてしまいそうなときに使う。そして、同じ種類の作業を同じ指示で何度も生成し続けているなら、その作業を専用のカスタムサブエージェントとして定義する、という基準です。サブエージェントはそれぞれ独立したコンテキストウィンドウの中で作業し、Claudeに戻ってくるのは要約された結果だけです。
なお公式ドキュメントは、サブエージェントは単一セッションの中で動く仕組みだと明記しています。多数の独立したセッションを並行して走らせて一か所から監視したい場合はバックグラウンドエージェント、複数のセッション同士でメッセージをやり取りしたい場合はクロスセッションメッセージング、Claudeが自らチームを立ち上げて統率する場合はエージェントチームという、それぞれ別の仕組みが用意されています。この違いや並列処理の全体像をもう少し詳しく知りたい方は、Claude Code Dynamic Workflowsの記事もあわせて参考にしてください。
なぜサブエージェントを使うとメインの会話が軽くなるのか
サブエージェントを使う効果は、公式ドキュメントで文脈の温存・制約の強制・設定の使い回し・役割の特化・コストの調整という5つに整理されています。
1つ目は文脈の温存です。調査や実装のための試行錯誤をメインの会話の外に追い出せます。2つ目は制約の強制で、そのサブエージェントが使えるツールを絞り込むことでできることを制限できます。3つ目は設定の使い回しで、ユーザーレベルのサブエージェントとして定義しておけば複数のプロジェクトで同じ定義を再利用できます。4つ目は役割の特化で、特定の領域に絞ったシステムプロンプトを与えることで挙動を専門化できます。5つ目はコストの調整で、Haikuのような速く安価なモデルへタスクを振り分けられるとされています。モデルごとの料金の違いを具体的に確認したい場合はClaude料金プラン比較の記事を参照してください。
Claudeは各サブエージェントのdescriptionフィールドを読んで、どのタイミングでどのサブエージェントに委任するかを判断します。このdescriptionは常に文脈を消費するため、公式ドキュメントは短く保つことを勧めています。ビルトインのものを除くサブエージェントの説明文の合計が15,000トークンを超えると、Claude Codeは起動時に合計トークン数を示す警告を表示すると公式ドキュメントに記載されています。詳細な説明は各サブエージェントのシステムプロンプト側に書き、descriptionフィールド自体は要点だけに絞る設計が推奨されています。
ビルトインサブエージェント:Explore・Plan・general-purposeの違い
Claude Codeには、Claudeが状況に応じて自動的に使うビルトインのサブエージェントがあらかじめ組み込まれています。
代表的なのがExplore、Plan、general-purposeの3種類です。それぞれの役割は次の表の通りです。
| ビルトイン名 | 使われる場面 | モデル | ツール |
|---|---|---|---|
| Explore | コードベースの検索・調査・ファイル発見(変更を伴わない) | メイン会話のモデル(メインがFableの場合などの例外は公式ドキュメント参照) | 読み取り専用。WriteとEditは拒否される |
| Plan | プランモード中に計画提示前のリサーチを行う | メイン会話のモデルを継承 | 読み取り専用。WriteとEditは拒否される |
| general-purpose | 調査と実行の両方が必要な複雑・多段階のタスク | 他にモデルの指定がなければ、環境変数CLAUDE_CODE_SUBAGENT_MODELがあればそのモデル、なければメイン会話のモデル | サブエージェントが使える全ツール |
| claude | どれにも当てはまらないタスクの受け皿。バックグラウンドセッションの既定 | サブエージェントとして呼ばれたときはモデル決定の優先順位に従う | サブエージェントが使える全ツール |
ExploreとPlanはリサーチを高速かつ低コストに保つため、CLAUDE.mdファイルと親セッションのgitステータスの読み込みをスキップする唯一のビルトインサブエージェントだと公式ドキュメントは説明しています。それ以外のビルトイン・カスタムサブエージェントは両方を読み込みます(カスタムサブエージェントはフロントマターでomitClaudeMd: trueを指定すると、CLAUDE.mdの読み込みを省略できます)。このほかにも、/statusline実行時に使われるstatusline-setup(Sonnet)や、Claude Codeの機能について質問したときに使われるclaude-code-guide(Haiku)といった補助的なエージェントも用意されています。
ビルトインサブエージェントは対話セッションで既定で登録されていますが、permissions.denyに特定の種類を追加すれば個別にブロックでき、Agentツール自体を拒否すればどのサブエージェントへの委任も止められます。ExploreとPlanだけを外したい場合は環境変数CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTSを1に設定する方法が案内されています。
サブエージェントの保存場所と優先順位
サブエージェントのファイルはどこに置くかによって、誰がそのサブエージェントを使えるかが決まります。
公式ドキュメントに示されている保存場所と優先順位は次の表の通りです。同じ名前のサブエージェントが複数の場所に存在する場合、優先順位が高い場所の定義が使われます。
| 保存場所 | スコープ | 優先順位 | 作り方 |
|---|---|---|---|
| Managed settings(マネージド設定のディレクトリ内の.claude/agents/にMarkdownを置く) | 組織全体 | 1(最高) | マネージド設定として配布 |
| –agents CLIフラグ | 現在のセッションのみ | 2 | Claude Code起動時にJSONを渡す |
| .claude/agents/ | 現在のプロジェクト | 3 | Claudeに依頼するか手動でファイル作成 |
| ~/.claude/agents/ | そのマシン上の全プロジェクト | 4 | Claudeに依頼するか手動でファイル作成 |
| プラグインのagents/ディレクトリ | プラグインが有効な範囲 | 5(最低) | プラグインのインストール |
プロジェクトのサブエージェント(.claude/agents/)は、作業ディレクトリからリポジトリのルートに向かって上に遡りながら走査されるため、途中にある.claude/agents/すべてがスキャン対象になります。同じnameを持つ定義が複数のネストされたディレクトリにある場合、作業ディレクトリに近いほうの定義が使われるとされています。ユーザーのサブエージェント(~/.claude/agents/)は、そのマシン上のすべてのプロジェクトで使える個人用の定義です。どちらも再帰的にスキャンされるため、サブフォルダに整理しても識別には影響しません。識別はnameフロントマターだけで決まるためです。
同じディレクトリ内でnameが重複すると、Claude Codeはファイルシステムの読み込み順で決まる1つだけを読み込みます。/doctorのセットアップチェックで、同じ名前を共有しているファイルが報告され、リネームや削除の提案が表示されると公式ドキュメントに記載されています。
設定ファイルの書き方:YAMLフロントマターの主要フィールド
サブエージェントの設定ファイルは、YAMLフロントマターに続けてMarkdownでシステムプロンプトを書くという1つの形式で統一されています。
公式ドキュメントに掲載されている例をそのまま示します。これは.claude/agents/code-reviewer.mdとして保存する想定のテンプレートです。
---
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.
フロントマター部分がサブエージェントのメタデータと設定を定義し、本文(Markdownの地の文)がそのままシステムプロンプトになります。サブエージェントのシステムプロンプトは、この本文に環境情報が加わったものになり、Claude Code自体のシステムプロンプトは含まれません（CLAUDE.mdやgitステータス、Claudeが書く委任メッセージは別途渡されます）。主なフロントマターフィールドは次の表の通りです(フィールド名はcamelCaseで、認識されないフィールドはエラーにならず無視されると公式ドキュメントに記載されています)。nameとdescriptionの2つだけが必須です。
| フィールド | 必須 | 内容 |
|---|---|---|
| name | 必須 | 一意の識別子(256文字以内)。「:」(プラグインのスコープ用)を含められず、先頭を「-」にもできない。ファイル名と一致させる必要はない |
| description | 必須 | Claudeがいつこのサブエージェントに委任すべきかの説明 |
| tools | 任意 | 使えるツールのリスト。省略時はサブエージェントが使える全ツールを継承 |
| disallowedTools | 任意 | 継承または指定したリストから取り除くツール |
| model | 任意 | 使用するモデル(sonnet・opus・haiku・fable・フルモデルID・inherit) |
| permissionMode | 任意 | 権限モード(default・acceptEdits・auto・dontAsk・bypassPermissions・planなど) |
| maxTurns | 任意 | 停止するまでの最大ターン数 |
| skills | 任意 | 起動時にコンテキストへ読み込むスキル。内容全体が挿入される |
| mcpServers | 任意 | このサブエージェントだけが使えるMCPサーバー |
| hooks | 任意 | このサブエージェントに限定したライフサイクルフック |
| memory | 任意 | 永続的なメモリのスコープ(user・project・local) |
| background | 任意 | trueにすると、Claudeがフォアグラウンドを求めてもバックグラウンドで動かす |
| effort | 任意 | 努力レベル(low・medium・high・xhigh・max。使える値はモデルによる) |
| omitClaudeMd | 任意 | trueにするとCLAUDE.mdの読み込みを省略(v2.1.271以降) |
| color | 任意 | 表示色(red・blue・green・yellow・purple・orange・pink・cyan) |
| isolation | 任意 | worktreeを指定すると、リポジトリの隔離コピー上で実行 |
Claude Codeは~/.claude/agents/と.claude/agents/を監視しており、ファイルを追加・編集すると数秒以内に変更を検知し、次の委任から更新後の定義が使われるとされています。ただし、新しいagentsディレクトリをそのスコープで初めて作った直後、--add-dirで追加したディレクトリ配下の.claude/agents/、そして--disable-slash-commands付きで起動したセッションの3つのケースでは再起動が必要になると公式ドキュメントは注意しています。
モデル指定の仕組み:sonnet・opus・haiku・inheritとCLAUDE_CODE_SUBAGENT_MODEL
modelフィールドは、そのサブエージェントがどのモデルで動くかを制御するフロントマターです。
指定できる値は、sonnet・opus・haiku・fableといったモデルエイリアス、claude-opus-5-5のようなフルモデルID(モデル一覧の公式ページにはClaude Fable 5.1・Opus 5.5・Sonnet 5.5・Haiku 5.5が現行モデルとして掲載されています)、そしてメイン会話と同じモデルを使うinheritです。modelフィールドを省略した場合にどのモデルが選ばれるかは、公式ドキュメントで次の優先順位が示されています。1つ目がClaudeが呼び出し時に個別に渡すmodelパラメータ、2つ目がサブエージェント定義のmodelフロントマター、3つ目が環境変数CLAUDE_CODE_SUBAGENT_MODEL、4つ目がメイン会話のモデルです(この順序はv2.1.251以降のもので、それ以前は環境変数が個別指定とフロントマターより優先されていました)。
すべてのサブエージェントを1つのモデルに統一したい場合は、CLAUDE_CODE_SUBAGENT_MODELに加えてCLAUDE_CODE_SUBAGENT_MODEL_FORCEを1に設定する方法が案内されています。例えばすべてのサブエージェントをHaikuで動かす設定は次のようになります。
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
"CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
}
}
このJSONは設定ファイルのenvブロックに書く形式で、設定ファイルと優先順位の公式ドキュメントによれば、個人用途なら~/.claude/settings.json、プロジェクトのチーム共有用なら.claude/settings.jsonに置く、という使い分けが説明されています。どのモデルで動いているかは/tasksコマンド(v2.1.242以降)で、サブエージェントの行に表示されると公式ドキュメントに記載されています。
使えるツールを制限する:toolsとdisallowedTools、MCPサーバーの範囲指定
toolsフィールドは許可リスト、disallowedToolsフィールドは拒否リストとして、サブエージェントが使えるツールを絞り込みます。
次の例は、Read・Grep・Glob・Bashだけを許可し、ファイルの書き換えやMCPツールを一切使わせない設定です。
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---
逆に、継承したツールプールからWriteとEditだけを除きたい場合はdisallowedToolsを使います。
---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---
両方を指定した場合はdisallowedToolsが先に適用され、残ったツールプールに対してtoolsが絞り込みをかけるという順序で処理されると公式ドキュメントに記載されています。両方のフィールドはmcp__サーバー名やmcp__サーバー名__*というパターンにも対応しており、特定のMCPサーバーが提供するツールをまとめて許可・拒否できます。なお、AskUserQuestionなど一部のツールは、toolsに書いてもサブエージェントからは取り除かれ（ExitPlanModeも、permissionModeがplanの場合を除いて取り除かれ）、バックグラウンドで動くサブエージェントは組み込みツールが絞られた状態で動くと公式ドキュメントに記載されています。claude --agentでメインスレッドとして動かすエージェントに限り、tools: Agent(worker, researcher)のように書いて起動できるサブエージェントの種類を絞ることもできます。MCPサーバーそのものの仕組みを詳しく知りたい方はMCPとはの解説記事を参照してください。
さらにmcpServersフィールドを使えば、そのサブエージェントだけが使えるMCPサーバーをフロントマター内でインラインに定義できます。メインの会話にはツールの説明文を読み込ませたくないが、特定のサブエージェントだけには使わせたい、というときに有効な方法です。ツール制限に加えてhooksフィールドでBashコマンドの内容そのものを検証するといった、より細かい安全対策も組み合わせられます。この種のセキュリティ設計についてはClaude Code GitHub Action セキュリティの記事もあわせて確認しておくと理解が深まります。
呼び出し方:自動委任・@メンション・セッション全体化
サブエージェントの呼び出し方には、Claudeに任せる自動委任と、自分で明示的に指定する方法の両方があります。
Claudeはリクエストのタスク内容、各サブエージェントのdescriptionフィールド、現在の文脈をもとに自動で委任するかどうかを判断します。積極的に委任させたい場合は、descriptionに「use proactively」のような明示的なフレーズを含めることが推奨されています。明示的に呼び出す方法は3段階でエスカレートします。1つ目は自然言語でサブエージェント名を挙げる方法で、委任するかどうかの最終判断はClaudeに委ねられます。2つ目は@に続けてサブエージェントを選ぶ@メンション(入力形式は@"code-reviewer (agent)" ...または@agent-code-reviewer)で、その1回のタスクに限り指定したサブエージェントが実行される仕組みです。ただし@メンションが決めるのは「どのサブエージェントを呼ぶか」で、渡されるプロンプトの内容までは決まりません。3つ目は--agentフラグや設定ファイルのagent設定で、セッション全体をそのサブエージェントのシステムプロンプト・ツール制限・モデルで動かす方法です。
サブエージェントの入れ子については、公式ドキュメントによると既定でメイン会話から3階層下まで、サブエージェントが別のサブエージェントを起動できます。環境変数CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHで深さを変更でき、1にすると入れ子を無効にできます。
サブエージェントはフォアグラウンドとバックグラウンドのどちらでも動きます。フォアグラウンドは完了するまでメインの会話をブロックし、権限確認のプロンプトはそのままあなたに渡されます。バックグラウンドは作業を続けながら並行して走らせられ、権限が必要な操作に達するとメインセッション側にプロンプトが表示されます。実行中のタスクはCtrl+Bでバックグラウンドに回せます。どちらで動くかは、環境変数CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1があればフォアグラウンド、forkモードが有効な環境(対話セッションの既定)ではバックグラウンド、forkモードが無効な環境ではClaudeが結果を待つ必要があるときだけフォアグラウンド、という順で決まり、フロントマターにbackground: trueを書けばバックグラウンドに固定できると公式ドキュメントに記載されています。委任がうまく機能するかどうかは説明文や指示の書き方に大きく左右されるため、Claudeのプロンプトのコツの記事で紹介されている書き方も参考になります。
会話全体を引き継ぐfork(/subtask)と通常のサブエージェントの違い
通常のサブエージェントは毎回まっさらな文脈から始まりますが、forkはそれまでの会話全体を丸ごと引き継いで動く特殊なサブエージェントです。
通常のサブエージェントは、会話履歴やすでに読み込んだファイル、これまで呼び出したスキルを見ることができません。Claudeが作成した委任メッセージから作業を始めるだけです。一方でforkは、システムプロンプト・ツール・モデル・これまでのメッセージ履歴のすべてをメインセッションと同じ状態で引き継ぎます。/subtaskコマンド(Claude Code v2.1.212以降。v2.1.161から v2.1.211までは/fork)で、forkモードが有効かどうかにかかわらず自分から起動できます(例:/subtask draft unit tests for the parser changes so far)。なおforkから別のforkを起動することはできません。両者の違いは次の表の通りです。
| 観点 | fork | 通常のサブエージェント |
|---|---|---|
| コンテキスト | 会話全体の履歴を引き継ぐ | 渡されたプロンプトだけのまっさらな文脈 |
| システムプロンプトとツール | メインセッションと同一 | サブエージェント定義ファイルに基づく |
| モデル | メインセッションと同一 | サブエージェントのmodelフィールドに基づく |
| プロンプトキャッシュ | メインセッションと共有 | 別のキャッシュ |
forkはシステムプロンプトとツール定義が親と同一なので、最初のリクエストで親のプロンプトキャッシュをそのまま再利用できます。そのため、同じ文脈が必要な作業をあらためて説明し直す新規サブエージェントより、forkのほうが安く済むケースがあるとされています。公式ドキュメントは、他のどのサブエージェントを使うにも背景説明が多すぎて非効率になる場面や、同じ出発点から複数のアプローチを並行して試したい場面でforkを使う、という基準を示しています。並列でのタスク処理をさらに広げた仕組みについてはClaude Code Dynamic Workflowsの記事で扱っています。
実践例:コードレビュー・デバッグ・データ分析のサブエージェント定義
公式ドキュメントには、目的別にツール権限を設計したサブエージェントのテンプレート例が掲載されています。
1つ目は読み取り専用のコードレビュー担当です。EditとWriteを与えず、コードを変更せずにレビューだけを行わせる設計です。
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
2つ目はデバッグ担当です。バグ修正にはファイルの変更が必要なため、コードレビュー担当とは違いEditを含めています。
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
3つ目はデータ分析担当です。SQLやBigQueryを使った分析のように、コーディング以外の専門領域向けのサブエージェントを作れる例として掲載されており、より高度な分析のためにmodel: sonnetを明示しています。
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---
SQLを使ったデータ分析をClaudeにどこまで任せられるかは、ClaudeでExcelのデータ分析の記事でも扱っているので、こちらのサブエージェント設計と合わせて読むと実務でのイメージがつかみやすくなります。
4つ目は読み取り専用のデータベース担当です。toolsフィールドだけでは制御しきれない細かい条件を、PreToolUseフックで補う例として紹介されています。Bashツール自体は許可しつつ、実行しようとしたコマンドがINSERTやUPDATEなどの書き込み系SQLかどうかをフックのスクリプトでチェックし、書き込みであればブロックします。
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
公式ドキュメントはこの4つの例を通じて、フォーカスを絞ったサブエージェントの設計・委任先を一意に決められる説明文・必要最小限のツール権限・バージョン管理へのコミットという4つのベストプラクティスを示しています。
サブエージェントを使うべき場面・使わないほうがいい場面
サブエージェントが向いているかどうかは、メインの会話を圧迫するかどうかと、そのタスクにこれまでの会話の文脈が必要かどうかで判断できます。
使うべき場面として公式ドキュメントの基準に当てはまるのは、大きなコードベースの探索やログの調査でメインの会話を検索結果まみれにしたくないとき、同じ種類の作業を同じ指示で繰り返し依頼しているとき、危険な操作をツール制限で防ぎたいとき、そして定型的な作業をHaikuのような安価なモデルに振り分けてコストを抑えたいときです。大規模なコードベースを一度に扱う実務上の規模感については、アルバータ州政府がClaude Codeで4.66億行を20時間でスキャンした事例の記事も参考になります。
逆に、いったん立ち止まって考えたほうがよい場面もあります。1つは、副次的な調査がメインの会話をほとんど圧迫しない程度の小さな作業です。この場合はわざわざ切り出す手間のほうが大きくなりがちだと読み取れます。2つ目は、すでにメインの会話で読み込んだファイルややり取りをそのまま使う必要があるタスクです。通常のサブエージェントは会話履歴を持たない新規の文脈から始まるため不向きで、この場合はforkのほうが公式ドキュメントの基準に合っています。3つ目は、descriptionフィールドを書き込みすぎているケースです。ビルトインを除くサブエージェントの説明文の合計が15,000トークンを超えると起動時に警告が出るため、と公式ドキュメントにある通り、増やしすぎない設計が必要です。4つ目は、プラグイン経由のサブエージェントでhooks・mcpServers・permissionModeを使いたい場合です。これらのフィールドはプラグインのサブエージェントでは無視される制約があるため、必要ならプロジェクトやユーザーのagents/配下にファイルをコピーする必要があります。
よくある質問（FAQ）
- Q1. サブエージェントとfork(/subtask)は何が違いますか。
- 通常のサブエージェントは毎回まっさらな文脈から始まり、会話履歴やすでに読んだファイルを見ることができません。forkはメインセッションのシステムプロンプト・ツール・モデル・会話履歴をそのまま引き継ぐ点が異なると公式ドキュメントに記載されています。
- Q2. サブエージェントの設定ファイルはどこに置けばよいですか。
- プロジェクト固有にしたい場合は
.claude/agents/、自分のマシン上の全プロジェクトで使いたい場合は~/.claude/agents/に置きます。組織全体に配布する場合はマネージド設定側の.claude/agents/を使う方法が案内されています。 - Q3. modelフィールドを省略すると、どのモデルが使われますか。
- Claudeが呼び出し時に渡すモデル指定、サブエージェント定義のmodelフロントマター、環境変数CLAUDE_CODE_SUBAGENT_MODEL、メイン会話のモデルという順番で解決されると公式ドキュメントに記載されています。
- Q4. サブエージェントに使わせるツールを制限するにはどうすればよいですか。
toolsフィールドで許可リストを、disallowedToolsフィールドで拒否リストを指定します。両方指定した場合はdisallowedToolsが先に適用され、残ったツールプールにtoolsが適用されます。MCPサーバー単位でまとめて許可・拒否するパターンにも対応しています。- Q5. サブエージェントのファイルを作成・編集したのに反映されないときはどうすればよいですか。
- 通常はファイルの追加・編集から数秒以内に検知され、次の委任から更新後の定義が使われます。ただし、そのスコープで初めて
agentsディレクトリを作った直後や、--add-dirで追加したディレクトリ配下、--disable-slash-commands付きで起動したセッションでは再起動が必要になると公式ドキュメントに記載されています。 - Q6. サブエージェントを増やしすぎると何が起きますか。
- ビルトインを除くサブエージェントの説明文(description)の合計が15,000トークンを超えると、Claude Codeは起動時に合計トークン数を示す警告を表示すると公式ドキュメントに記載されています。詳細な指示はシステムプロンプト側に書き、descriptionは短く保つ設計が推奨されています。
まとめ
サブエージェントは、メインの会話を汚さずに副次的な作業を切り出すための公式の仕組みです。設定ファイルの実体はYAMLフロントマター付きのMarkdownで、置き場所は.claude/agents/か~/.claude/agents/の2択から考え始めればよく、必須のフィールドはnameとdescriptionだけです。まずは公式ドキュメントに掲載されている読み取り専用のコードレビュー担当の例をそのまま自分のプロジェクトの.claude/agents/に置いてみて、Claudeに委任させてみるところから試すのが再現しやすい進め方です。会話履歴をそのまま引き継がせたい場面が出てきたら、そこで初めてforkの出番だと考えれば、使い分けに迷いにくくなります。
Claude Code全体の活用の幅を広げたい方はClaude活用の使い方の記事もあわせてご覧ください。
あわせて読みたい・姉妹メディア
