サブエージェントとは、Markdown1枚に権限とツールを絞り込んで定義する、独立した文脈で動く子のAIです。Claude Codeでは、この定義ファイルを使って複数体を並列起動し、結果だけを親の会話へ戻せます。本記事は、定義ファイルの書き方、親から子へ渡る情報の範囲、並列起動と結果統合の実装、権限の絞り方を、公式ドキュメントと自社の.claude/agents/実例3本から示します。検証環境は2026-07-28時点の公式ドキュメント記載です。
01結論｜サブエージェント定義でできるようになる3つのこと
本記事を読むと、次の3点ができるようになります。
- サブエージェント定義ファイルをMarkdown＋YAMLで自分で書ける
- 親から子へ渡る情報と渡らない情報を切り分け、
tools・skillsで権限を絞れる - 複数のサブエージェントを並列起動し、結果をディレクター役が統合する実装を再現できる
サブエージェントをいつ使い、判断役と実行役をどう分けるかという設計思想そのものは『サブエージェント設計｜ディレクターとワーカーの分け方』で扱っています。本記事は、その設計を実際の定義ファイルへ落とし込む実装だけに絞ります。
WEBMARKSは.claude/agents/配下の3ファイル（jp-writer・vault-researcher・bulk-processor）でこの構成を社内実装しています（2026-07-28時点）。以降の実コードはこの3ファイルからの引用です。
02前提｜Claude Codeで子エージェントを試す環境とスコープ
検証環境は、Claude Code公式ドキュメント（code.claude.com/docs、2026-07-28時点の記載）です。加えて、自社の.claude/agents/定義ファイル3本も参照します。サブエージェント定義ファイルは、置く場所によって適用範囲と優先度が変わります（出典: Claude Code公式ドキュメント）。
| 保存場所 | 適用範囲 | 優先度 | 作り方 |
|---|---|---|---|
| Managed settings | 組織全体 | 1（最高） | 管理者がmanaged settingsで配布 |
--agents CLIフラグ | そのセッションのみ | 2 | 起動時にJSONを渡す（ディスクに保存されない） |
.claude/agents/（プロジェクト） | そのプロジェクト | 3 | Claudeに依頼、または手書き |
~/.claude/agents/（ユーザー） | 全プロジェクト共通 | 4 | Claudeに依頼、または手書き |
プラグインのagents/ディレクトリ | プラグイン有効時 | 5（最低） | プラグイン導入時に自動 |
同じnameのサブエージェントが複数の場所にあると、優先度の高い場所の定義が使われます。WEBMARKSはプロジェクト共有を前提に.claude/agents/を採用しています。jp-writer・vault-researcher・bulk-processorの3ファイルをGit管理下に置いています。
プロジェクト用は、実行時のカレントディレクトリからリポジトリルートまでの間にある.claude/agents/を全て走査します。新規に作ったagentsディレクトリは、セッション開始時に存在しなかった場合、そのセッション中は検知されません（詳細は後述のつまずきポイント）。
03子エージェントの定義ファイルをMarkdown＋YAMLで書く
サブエージェントの定義ファイルは、先頭のYAML frontmatterと、それに続くMarkdown本文（システムプロンプトになる）で構成されます。frontmatterで必須なのはnameとdescriptionの2つだけです（出典: Claude Code公式ドキュメント）。
| フィールド | 必須 | 書く内容 |
|---|---|---|
name | 必須 | 一意な識別子。小文字とハイフンのみ |
description | 必須 | Claudeがいつこのサブエージェントへ委譲すべきかの説明 |
tools | 任意 | 使える道具のリスト（省略時は継承） |
disallowedTools | 任意 | 継承したリストから除外する道具 |
model | 任意 | sonnet／opus／haiku／inherit（省略時はinherit） |
自社の実例です。.claude/agents/jp-writer.mdは、日本語ドラフトの執筆だけを担う実働ワーカーとして次のように定義しています。
---
name: jp-writer
description: 日本語の成果物ドラフト（記事・提案文・スライド原稿・メール文面・レポート本文・図解の文言・ナレッジ記事など）を実際に執筆・制作する実働ワーカー。Fable（ディレクター）が構成・要件・保存先を決めた後、本文の執筆やファイル作成という「手を動かす」部分を委譲する先。大量の文章を書く／既存ドキュメントを整形・加筆する作業はこのワーカーに投げる。
tools: Read, Write, Edit, Glob, Grep
model: sonnet
---
あなたはWEBMARKS Vault の**日本語執筆・制作の実働ワーカー**です。上位モデル（Fable＝ディレクター）
から渡された指示に従い、成果物の本文を実際に書き、ファイルとして保存するのが役割です。descriptionが委譲の判定材料です。Claudeはタスクの説明とdescriptionフィールド、現在の文脈を突き合わせて自動委譲するかを決めます（出典: Claude Code公式ドキュメント）。積極的な委譲を促したい場合は、descriptionに「proactively」に相当する語（自発的に使う旨）を含めます。
呼び出し方法は3段階あります。1つ目は、自然言語でサブエージェント名を挙げる方法です。2つ目は、@で名指しして必ずそのサブエージェントを使わせる方法です。3つ目は、--agentフラグでセッション全体をそのサブエージェントの権限・モデルで走らせる方法です（出典: Claude Code公式ドキュメント）。
04親から子エージェントへ渡る情報をtools・skillsの指定で絞り込む
サブエージェントは、フォーク（会話全体を引き継ぐ特殊なコピー）でない限り、常に新しい独立した文脈で始まります。会話履歴も、既に呼んだスキルも、既に読んだファイルも引き継ぎません（出典: Claude Code公式ドキュメント）。
起動時に渡るのは次の4点です。
- システムプロンプト：定義ファイルのMarkdown本文＋環境情報（Claude Code全体のシステムプロンプトそのものではない）
- タスクメッセージ：親が委譲時に書く指示文
- CLAUDE.md階層：親が読み込む全レベル（
~/.claude/CLAUDE.md・プロジェクトのCLAUDE.md・managed policy） - Gitステータス：親セッション開始時点のスナップショット
組み込みのExploreとPlanだけは、CLAUDE.mdとGitステータスを読み込みません。出力スタイル（フォーク時を除く）と、親セッションの自動メモリ（auto memory）は、いずれの場合も子へは渡りません。memoryフィールドを指定しても、親の自動メモリが渡るわけではありません。子専用の独立した永続メモリディレクトリを新たに持たせられるだけです（出典: Claude Code公式ドキュメント）。
権限を絞る手段はtoolsとdisallowedToolsの2つです。toolsは許可リスト、disallowedToolsは拒否リストとして働きます。両方指定した場合はdisallowedToolsが先に適用され、残った候補に対してtoolsが解決されます（出典: Claude Code公式ドキュメント）。
---
name: vault-researcher
description: Vault内の資料調査・棚卸し・事実確認や、Web上の一次情報の収集・裏取りを行う読取専用の調査ワーカー。Fable（ディレクター）が「この論点を調べて」「この案件の現状を洗って」と投げる先。ファイルは書かず、調べた事実を構造化して返す。設計判断そのものはディレクターが行う。
tools: Read, Glob, Grep, WebFetch, WebSearch
model: sonnet
---vault-researcherはWriteもEditも持たず、書き込む道具そのものが与えられていないため、勝手にファイルを書き換えることが構造的にできません。3ファイルともBashを含んでいません。社内規約は、この構成を「実働ワーカーにBashを渡していないのが担保」と明文化しています。送信・削除・pushはBash経由の操作が多いため、道具を渡さない設計そのものが人間ゲートの一部です。
skillsフィールドは道具ではなく知識を絞り込みます。指定したスキルの中身を起動時にまるごと注入し、子が実行中に自分で探す手間を省く仕組みです（出典: Claude Code公式ドキュメント）。skillsを書かなくても、toolsからSkillを外していない限り、子は他のスキルを自分で呼び出せます。スキル呼び出しごと禁止したい場合は、toolsにSkillそのものを含めません。
05子エージェントを並列起動し、結果をディレクターが統合する
独立した調査は、複数のサブエージェントを同時に走らせられます。公式ドキュメントは「認証・データベース・APIモジュールを、別々のサブエージェントを使って並列に調査して」という依頼文を例に挙げています。各サブエージェントが独立に探索した後、結果をClaudeが統合すると説明しています（出典: Claude Code公式ドキュメント）。
同時実行には3種類の上限があります。
| 上限の種類 | 既定値 | 変更する環境変数 | 到達したときの挙動 |
|---|---|---|---|
| 深さ上限（親から何層まで子を生めるか） | 3層 | CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH | 上限に達したサブエージェントからAgentツールが外れる |
| 同時実行上限 | 20体 | CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS | 新規起動がConcurrent subagent limit reachedで失敗 |
| セッション累計上限 | 200体 | CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION | 新規起動がSubagent spawn limit reachedで失敗 |
深さ上限の既定値はバージョンで変わっています。v2.1.172〜v2.1.216は5層固定、v2.1.217〜v2.1.218は既定1層、v2.1.219以降は既定3層です（出典: Claude Code公式ドキュメント）。上限に達しても即エラーにはならず、「自分で作業して1つの要約を返す」動作へ切り替わります。
WEBMARKSの運用ルールは、上限いっぱいの20体ではなく「同時最大で実務上4〜6本」を目安にしています。理由は、サブエージェントの結果が親の会話へ戻ってくるためです。詳細な結果を返すサブエージェントを大量に走らせると、親側のコンテキストを消費すると公式ドキュメントも警告しています（出典: Claude Code公式ドキュメント）。並列起動した後は、各ワーカーの成果を必ず突合してから統合する手順を明文化しています。
Fableへの委譲プロンプトの型（社内実例を要約）:
1. ゴール：何を作る／調べるのか（1文）
2. スコープ：やる範囲とやらない範囲
3. 入力：読むべき実ファイルパス・URL
4. 出力形式と保存先：どこに何形式で
5. 制約：人間ゲート厳守・未確認は※要確認
6. 返し方：作ったファイルの絶対パスと要点だけこの型に沿ってjp-writer・vault-researcher・bulk-processorへ同時に指示を出します。3体は互いを認識せず独立に作業し、ディレクター役へそれぞれの結果だけが返ります。統合はディレクター役の仕事であり、サブエージェント同士が結果をすり合わせることはありません。
06子エージェントの委譲でつまずきやすい3つのポイント
つまずき1：新しく作ったagentsディレクトリが認識されない。Claude Codeは~/.claude/agents/と.claude/agents/の変更を数秒で検知します。ただし対象は、セッション開始時点で存在していたディレクトリに限られます。あるスコープで初めてagentsディレクトリを作った直後は、セッションを再起動するまで読み込まれません（出典: Claude Code公式ドキュメント）。
つまずき2：toolsのリストが1つも解決できず起動に失敗する。toolsに書いた指定子が綴りミスや存在しないツール名で、1つも実際のツールに解決できない場合があります。この場合Claude Codeは起動そのものを拒否し、解決できなかった項目名を含むエラーを返します（v2.1.208以降、出典: Claude Code公式ドキュメント）。それより前のバージョンでは、道具ゼロのまま起動し、空や要領を得ない結果を返していました。
つまずき3：並列数が上限に達して追加の起動が失敗する。同時実行上限（既定20）に達した状態で新しいサブエージェントを起動しようとするとConcurrent subagent limit reachedで失敗します。実行中の数が上限を下回れば再び起動できるようになりますが、リトライすべきではないと公式ドキュメントは明記しています（出典: Claude Code公式ドキュメント）。
07動作確認の方法｜サブエージェントが定義どおりに動いたと判定する基準
定義ファイルを書いたら、次の4項目で動作を確認します。1つでもズレたらtoolsの綴りとdescriptionの文言を見直します。
- 自動委譲を試す：
descriptionに合う依頼を自然言語で出す。期待：Claudeがそのサブエージェントへ自動的に委譲する。 - 明示呼び出しを試す：
@でサブエージェント名を指定する。期待：狙った定義が必ず使われる（自動判定を待たない）。 - 権限の絞り込みを試す：
toolsに含めていない操作（例：Writeを渡していないサブエージェントにファイル編集を頼む）を実行させる。期待：その操作を実行できないか、拒否される。 - 並列統合を試す：独立した調査を2〜3件、同じ依頼文で並列起動させる。期待：各結果が親の会話へ戻り、ディレクター役がそれらを突合して1つの結論にまとめられる。
4項目すべてで期待どおりの挙動が出れば、定義ファイルは意図どおりに機能しています。
08FAQ
サブエージェントとメインの会話は同じCLAUDE.mdを読みますか
読みます。組み込みのExploreとPlanを除く全てのサブエージェント（カスタム定義を含む）は、親が読み込む全レベルのCLAUDE.mdを引き継ぎます。ExploreとPlanだけは、調査を高速・低コストに保つためCLAUDE.mdとGitステータスを省略します。
サブエージェントに前の会話の文脈は渡りますか
渡りません。フォーク（会話全体を引き継ぐ特殊な仕組み）を使わない限り、サブエージェントは毎回、新しい独立した文脈で始まります。渡したい情報は、委譲時のタスクメッセージに明示的に書く必要があります。
並列で起動できるサブエージェントの数に上限はありますか
あります。同時実行の既定上限は20体、セッションを通じた累計の既定上限は200体です。どちらも環境変数で変更できますが、無効化はできません。WEBMARKSは既定の20体ではなく、実務上4〜6体を目安に運用しています。
サブエージェントは自分の判断で送信や削除ができますか
toolsに何を渡すか次第です。Bashや送信系のMCPツールを渡さなければ、その操作は構造的に実行できません。WEBMARKSの3つの実働ワーカーはいずれもBashを持たない設計で、送信・削除・pushを人間ゲートの外に出さない仕組みにしています。
プラグインで配布されたサブエージェントでも同じ書き方ができますか
frontmatterの基本フィールドは同じです。ただしセキュリティ上の理由から、プラグイン由来のサブエージェントではhooks・mcpServers・permissionModeフィールドが無視されます。これらを使いたい場合は、定義ファイルを.claude/agents/か~/.claude/agents/へコピーします。
