「サブエージェントを使うと手が増える、というのは分かりました。それで、何をどこに書けばいいんですか」。Claude Codeの話をしていると、だいたいこの質問で止まります。

止まる理由ははっきりしています。サブエージェントは、設定画面のスイッチではなく、Markdown1枚に権限と道具を書き込んで作る「子」だからです。どこに置くか、何を書くか、書かなかったときに何が起きるか。この3つを知らないまま手を動かすと、動いたのか動いていないのかも判定できません。

この記事は、定義ファイルの書き方と、親から子へ何が渡って何が渡らないか、そして並列で走らせたときにどこで頭打ちになるかを扱います。素材は公式ドキュメントの記載と、運営元WEBMARKSが実際に置いている定義ファイル3本です。

こんなふうに調べていませんか

  • サブエージェントを作れと言われたが、ファイルに何を書くのかが分からない
  • 親の会話をどこまで引き継ぐのかが読めず、指示文をどこまで書くべきか決められない
  • 並列で走らせたら止まった。上限に当たったのか、書き方が悪いのかを切り分けたい

この記事を読み終えたときに手に入るもの

  • 定義ファイルのfrontmatterを、必須の項目から自分で書けるようになります
  • 親から子へ渡る情報と渡らない情報を切り分けて、指示文に何を書くかを決められるようになります
  • 並列で詰まった場所を、上限の種類ごとに切り分けられるようになります

結論30秒でわかる、この記事の結論

  • サブエージェントとは、専用の権限・道具・システムプロンプトを持ち、独立した文脈で動く子のAIです。定義はMarkdown1枚で足ります。
  • frontmatterで欠かせないのはnamedescriptionだけ。残りは、渡す道具と使うモデルを狭めるための任意項目です。
  • 親の会話は子へ渡りません。渡したいことは、委譲するときの指示文に書き出します。
定義ファイル1枚で決まるのは、この3つです書き足す作業ではなく、削る作業になります定義ファイル1枚で決まるのは、この3つです決まる①呼ばれ方説明欄の文面が、出番を決めます決まる②持てる道具渡さないと決めたほうが強く効きます決まる③見える範囲親の会話は、持っていきません鈴木さん書き足す作業ではなく、削る作業になります
定義ファイル1枚で決まるのは、この3つです — 書き足す作業ではなく、削る作業になります

進行役は3人です。若葉さんが用語の側から、高梨課長が自分の手で動かす側から聞き、鈴木さん(本誌監修)が答えます。

01Claude Codeのサブエージェントって、結局なにが「子」なんですか?

若葉さん
若葉さんの発言

サブエージェントって、AIがもう1体増えるという理解でいいんでしょうか。

鈴木さん
鈴木さんの発言

増えるというより、別の机に座ってもらう感じに近いです。同じ部屋にはいますが、こちらの会話は聞こえていません。

サブエージェントとは、専用の権限・道具・システムプロンプトを持ち、独立した文脈で動く子のAIです。Claude Codeでは、この定義ファイルを使って複数体を並列起動し、結果だけを親の会話へ戻せます。

「子」と呼ぶのは、生まれ方と別れ方が決まっているからです。親のセッションが起動を決め、親の書いた指示文を持って動き出し、終わったら結果だけを親へ返します。それ以外のものは、行きも帰りも運びません。

編集部にたとえると、こうなります机は増えますが、打ち合わせは増えません編集部にたとえると、こうなります机は増えますが、打ち合わせは増えません編集部でいうとClaude Codeでいうと取材に出る記者サブエージェント記者どうしは顔を合わせない独立した文脈手渡された取材メモがすべて委譲するときの指示文原稿を束ねる編集長ディレクター役の親
編集部にたとえると、こうなります — 机は増えますが、打ち合わせは増えません

ここで押さえておきたいのは、増えるのが「賢さ」ではないという点です。増えるのは机の数で、1つの机から見える範囲はむしろ狭くなります。狭いほうが、頼んだ仕事から外れにくくなります。

サブエージェントをいつ使い、判断役と実行役をどう分けるかという設計思想そのものは、サブエージェント設計|委譲の線引きと3つの失敗で扱っています。本記事は、その設計を実際の定義ファイルへ落とし込む実装だけに絞ります。

WEBMARKSは.claude/agents/配下の3ファイル(jp-writer・vault-researcher・bulk-processor)でこの構成を社内実装しています(2026-07-24設置、2026-08-03に実体を再実測)。以降の実コードは、この3ファイルからの引用です。

この章のまとめ

子は、親の記憶ではなく親の指示文を持って動きます。だから定義ファイルは、賢く書くより狭く書くほうが効きます。

02サブエージェントの定義ファイルは、どこに置くと効くんですか?

定義ファイルは、置く場所によって適用範囲と優先度が変わります(出典: Claude Code公式ドキュメント)。

保存場所適用範囲優先度作り方
Managed settings組織全体1(最高)管理者がmanaged settingsで配布
--agents CLIフラグそのセッションのみ2起動時にJSONを渡す(ディスクに保存されない)
.claude/agents/(プロジェクト)そのプロジェクト3Claudeに依頼、または手書き
~/.claude/agents/(ユーザー)全プロジェクト共通4Claudeに依頼、または手書き
プラグインのagents/ディレクトリプラグイン有効時5(最低)プラグイン導入時に自動

同じnameのサブエージェントが複数の場所にあると、優先度の高い場所の定義が使われます。つまり、置き場を選ぶという行為は、そのまま「誰の書いた定義に負けるか」を選ぶ行為でもあります。

プロジェクト用は、実行時のカレントディレクトリからリポジトリルートまでの間にある.claude/agents/を全て走査します。手元で開いているフォルダの深さによって、拾われる定義が変わるということです。

同じ名前が並んだとき、どれが残るか上にあるほうが、下を押しのけます同じ名前が並んだとき、どれが残るか上にあるほうが、下を押しのけます会社から配られた分(最上段)手元では上書きできません起動のときに、その場で渡した分その回かぎりで消えますこの案件のフォルダに置いた分案件ごとに体制を変えられます自分のホームに置いた分どの案件を開いても付いてきますプラグインが持ってくる分(土台)名前がぶつかったら、まっ先に譲ります置き場を決めることは、誰に譲るかを決めることでもあります。
同じ名前が並んだとき、どれが残るか — 上にあるほうが、下を押しのけます

WEBMARKSは、全プロジェクトへ効かせるのではなく、このリポジトリ専用の体制として.claude/agents/を選びました。ただしこの3ファイルはGitの追跡対象に入れていません(2026-08-03実測。git statusで未追跡)。この選択には後で効いてくる副作用があり、後半のつまずきで扱います。

この章のまとめ

置き場の選択は、適用範囲の選択であると同時に、上書きされる順番の選択でもあります。

03サブエージェントを作るとき、AIエージェントの定義ファイルには最低限なにを書けばいいんですか?

定義ファイルは、先頭のYAML frontmatterと、それに続くMarkdown本文(システムプロンプトになる)で構成されます。frontmatterで欠かせないのはnamedescriptionの2つだけです(出典: Claude Code公式ドキュメント)。

フィールド必須書く内容
name必須一意な識別子。小文字とハイフンのみ
description必須Claudeがいつこのサブエージェントへ委譲すべきかの説明
tools任意使える道具のリスト(省略時は継承)
disallowedTools任意継承したリストから除外する道具
model任意sonnetopushaikuinherit(省略時はinherit

任意項目を書かなかったときの既定が、それぞれ違う向きを向いている点に注意してください。toolsを省くと道具は継承されて広いままになり、modelを省くと親と同じモデルになります。省略は「安全側に倒れる」わけではありません。

04サブエージェントの本文には、システムプロンプトとして何を書くんですか?

自社の実例です。.claude/agents/jp-writer.mdは、日本語ドラフトの執筆だけを担う実働ワーカーとして次のように定義しています。

---
name: jp-writer
description: 日本語の成果物ドラフト(記事・提案文・スライド原稿・メール文面・レポート本文・図解の文言・ナレッジ記事など)を実際に執筆・制作する実働ワーカー。Fable(ディレクター)が構成・要件・保存先を決めた後、本文の執筆やファイル作成という「手を動かす」部分を委譲する先。大量の文章を書く/既存ドキュメントを整形・加筆する作業はこのワーカーに投げる。
tools: Read, Write, Edit, Glob, Grep
model: sonnet
---

あなたはWEBMARKS Vault の**日本語執筆・制作の実働ワーカー**です。上位モデル(Fable=ディレクター)
から渡された指示に従い、成果物の本文を実際に書き、ファイルとして保存するのが役割です。

見ていただきたいのは、書いてある量の少なさです。任意項目はtoolsmodelだけで、あとは名前と説明文と、システムプロンプトになる数行しかありません。

本文に置いてあるのは手順ではなく、立ち位置です。「あなたは何をする側の人で、判断は誰がするのか」を先に書いてあります。手順を長々と書いても、子が受け取る指示文は毎回変わるので、そこで上書きされてしまいます。変わらない部分だけを本文に残す、という分け方になります。

この章のまとめ

定義ファイルの本文は説明書ではなく、役どころの宣言です。毎回変わることは指示文へ、変わらないことだけを本文へ置きます。

05Claude Codeは、どのサブエージェントへ委譲するかをどう決めているんですか?

高梨課長
高梨課長の発言

名前を呼ばなくても勝手に選ばれる、と聞きました。何を見て選んでいるんでしょう。

鈴木さん
鈴木さんの発言

descriptionです。あそこは説明欄というより、応募要項に近いと思っています。書いていない仕事は、まわってきません。

descriptionが委譲の判定材料です。Claudeはタスクの説明とdescriptionフィールド、現在の文脈を突き合わせて自動委譲するかを決めます(出典: Claude Code公式ドキュメント)。積極的な委譲を促したい場合は、descriptionに「proactively」に相当する語(自発的に使う旨)を含めます。

判定に使われるのが説明欄のほうだ、という点はつまずきどころです。呼ばれないときに本文(システムプロンプト)を書き足しても、判定そのものは変わりません。直す欄を間違えると、いくら書き足しても手応えが出ないままになります。

06サブエージェントを名指しする場合と自動委譲では、AIエージェントの呼び出し方はどう違うんですか?

呼び出し方法は3段階あります(出典: Claude Code公式ドキュメント)。

  1. 自然言語で名前を挙げる:会話の中でサブエージェント名に触れる、いちばんゆるい呼び方です。
  2. @で名指しする:自動判定を待たず、そのサブエージェントを使わせます。
  3. --agentフラグを渡す:セッション全体を、そのサブエージェントの権限とモデルで走らせます。

下へ行くほど、こちらの意図が強く効きます。逆に言えば、いちばん上の呼び方しか使っていないうちは、選ばれるかどうかをdescriptionの書き方に委ねたままだということです。

書いた定義を試したい段階では、下の2つから入るほうが切り分けが速くなります。名指しで動くのに自動では呼ばれないなら、原因は定義の中身ではなく説明欄の書き方に絞れます。

この章のまとめ

呼び出し方を変えると、切り分けができます。名指しで動くかどうかが、説明欄の問題か中身の問題かの分かれ目になります。

07親の会話や読んだファイルは、サブエージェントにも渡るんですか?

若葉さん
若葉さんの発言

親のほうでさんざん説明したので、その続きから始めてくれると思っていました。

鈴木さん
鈴木さんの発言

そこが最初のつまずきどころです。子は、さっきまでの話を聞いていません。引き継ぎ書を持たせるつもりで書くほうが、結果が安定します。

サブエージェントは、フォーク(会話全体を引き継ぐ特殊なコピー)でない限り、常に新しい独立した文脈で始まります。会話履歴も、既に呼んだスキルも、既に読んだファイルも引き継ぎません(出典: 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公式ドキュメント)。名前から期待する動きと、実際の動きが食い違いやすい項目です。

この4点を裏返すと、指示文に書くべきものが決まります。親の画面には出ているのに子には見えていないもの、つまり会話で決めた前提・すでに開いたファイルのパス・そこまでの経緯が、そのまま書き出す対象になります。

この章のまとめ

子に見えていないものは、存在しないのと同じです。指示文は説明ではなく、持ち物リストとして書きます。

08AI社員として動くサブエージェントに渡す道具は、toolsとdisallowedToolsでどう絞るんですか?

権限を絞る手段はtoolsdisallowedToolsの2つです。toolsは許可リスト、disallowedToolsは拒否リストとして働きます。両方指定した場合はdisallowedToolsが先に適用され、残った候補に対してtoolsが解決されます(出典: Claude Code公式ドキュメント)。

手元に残る道具が決まるまで消えたものは、あとから戻ってきません手元に残る道具が決まるまで消えたものは、あとから戻ってきません1継承した候補省くと、広いまま入ってきます2拒否リストで削るこちらが先に効きます3許可リストで選ぶ残った候補から解決されます4手元に残るここに無い操作は起こりません
手元に残る道具が決まるまで — 消えたものは、あとから戻ってきません

順番が効いてくるのは、両方を書いたときです。拒否リストで消えたものは、許可リストに書いてあっても戻ってきません。強いのは、渡さないと決めたほうです

---
name: vault-researcher
description: Vault内の資料調査・棚卸し・事実確認や、Web上の一次情報の収集・裏取りを行う読取専用の調査ワーカー。Fable(ディレクター)が「この論点を調べて」「この案件の現状を洗って」「この主張の根拠を確認して」と投げる先。ファイルは書かず、調べた事実を構造化して返す。設計判断そのものはディレクターが行う。
tools: Read, Glob, Grep, WebFetch, WebSearch
model: sonnet
---

vault-researcherはWriteEditも持ちません。書き込む道具そのものが与えられていないため、勝手にファイルを書き換えることが構造的にできません。禁止と書いて守らせるのではなく、手が届かない状態にしてあります。

3ファイルともBashを含んでいません。社内規約は、この構成を「実働ワーカーにBashを渡していないのが担保」と明文化しています。送信・削除・pushはBash経由の操作が多いため、道具を渡さない設計そのものが人間ゲートの一部になっています。

09サブエージェントのskillsフィールドで、AI活用に必要な知識だけを渡せるんですか?

skillsフィールドは、道具ではなく知識を絞り込みます。指定したスキルの中身を起動時にまるごと注入し、子が実行中に自分で探す手間を省く仕組みです(出典: Claude Code公式ドキュメント)。

ここで誤解しやすいのは、絞り込みの向きです。skillsを書かなくても、toolsからSkillを外していない限り、子は他のスキルを自分で呼び出せます。つまりskillsは入口を閉じる欄ではなく、最初から手元に置いておく分を決める欄です。スキル呼び出しごと止めたい場合は、toolsSkillそのものを含めません。

10サブエージェントを並列で走らせると、どこで頭打ちになるんですか?

高梨課長
高梨課長の発言

独立した調査なら同時に投げたいのですが、どこかで詰まりますよね。

鈴木さん
鈴木さんの発言

詰まり方が3種類あります。厄介なのは、そのうち1つが「エラーにならずに静かに変わる」ことです。

独立した調査は、複数のサブエージェントを同時に走らせられます。公式ドキュメントは「認証・データベース・APIモジュールを、別々のサブエージェントを使って並列に調査して」という依頼文を例に挙げています(出典: 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で失敗
上限に当たったとき、気づけるかどうか止まり方が違うので、見る場所も変わります上限に当たったとき、気づけるかどうか止まり方が違うので、見る場所も変わります黙って切り替わる深さの上限に届いたとき子を生む道具が外れる自分で片づけて要約を返す画面には結果が出るので、成功に見えますその場で失敗する同時と累計の上限に届いたとき起動しようとして弾かれる決まった文言で止まる文言が出るぶん、気づけます
上限に当たったとき、気づけるかどうか — 止まり方が違うので、見る場所も変わります

深さ上限に達しても、即エラーにはなりません。「自分で作業して1つの要約を返す」動作へ切り替わります。画面には結果が返ってくるので、うまくいったように見えます。切り分けたいときに見るのは、返ってきた結果ではなく、子が起動したかどうかのほうです。

11既定値がバージョンで変わると、サブエージェントの並列は何が変わるんですか?

深さ上限の既定値は、バージョンで変わってきました。v2.1.172〜v2.1.216は5層固定、v2.1.217〜v2.1.218は既定1層、v2.1.219以降は既定3層です(出典: Claude Code公式ドキュメント)。

深さの既定値がたどってきた道すじ手元の版で、読み方が変わります深さの既定値がたどってきた道すじ手元の版で、読み方が変わりますv2.1.172〜v2.1.216動かせなかった時期設定を見なくても同じでしたv2.1.217〜v2.1.218いちばん浅かった時期そのままでは孫が生まれませんv2.1.219以降いまの初期設定古い手順書とは前提が合いません
深さの既定値がたどってきた道すじ — 手元の版で、読み方が変わります

この推移で効いてくるのは、数字そのものよりも「手元の版を見ないと判断できない」という事実のほうです。記事や社内メモに書いてある既定値は、書かれた時点の版のものです。挙動が食い違ったとき、書き方を疑う前にバージョンを疑うほうが早く着地します。

なお、既定値はCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHで上書きできます。区間がどれであっても、明示した値のほうが効きます。版に振り回されたくない場面では、既定に任せず書いてしまうのが確実です。

この章のまとめ

既定値は、仕様というより「その版での初期設定」です。共有する手順書には、既定に頼らず明示した値を書いておくほうが長持ちします。

12並列で走らせたサブエージェントの結果は、誰がまとめるんですか?

各サブエージェントが独立に探索した後、結果をClaudeが統合すると公式ドキュメントは説明しています(出典: Claude Code公式ドキュメント)。統合はディレクター役の仕事であり、サブエージェント同士が結果をすり合わせることはありません。互いを認識しないまま作業し、それぞれの結果だけが親へ返ります。

WEBMARKSの運用ルールは、上限いっぱいの20体ではなく「同時最大で実務上4〜6本」を目安にしています。理由は、サブエージェントの結果が親の会話へ戻ってくるためです。詳細な結果を返すサブエージェントを大量に走らせると、親側のコンテキストを消費すると公式ドキュメントも警告しています(出典: Claude Code公式ドキュメント)。

投げ方の型も決めてあります。

Fableへの委譲プロンプトの型(社内実例を要約):
1. ゴール:何を作る/調べるのか(1文)
2. スコープ:やる範囲とやらない範囲
3. 入力:読むべき実ファイルパス・URL
4. 出力形式と保存先:どこに何形式で
5. 制約:人間ゲート厳守・未確認は※要確認
6. 返し方:作ったファイルの絶対パスと要点だけ

社内規約は、この型を使って独立したタスクを1つのメッセージで複数ワーカーへ同時に投げ、各ワーカーの成果はディレクターが突合してから統合する、と定めています(出典: 社内規約)。

型の最後にある「要点だけ返す」が、並列数の目安と直結しています。返ってくる量を短くしておかないと、走らせた数だけ親の会話が埋まります。並列で得た時間を、統合の手間で失わないための決めごとです。

この章のまとめ

並列化の設計は、起動する側だけでなく、返ってくる量の設計とセットになります。

13定義したはずのサブエージェントが動かないのは、なにが原因ですか?

高梨課長
高梨課長の発言

書いたはずのサブエージェントが呼ばれません。書き方が悪いのか、そもそも読まれていないのか、切り分けがつかなくて。

鈴木さん
鈴木さんの発言

読まれていない側のほうが多い印象です。書いた本人からは見えにくい抜け方をします。

つまずき1:新しく作ったagentsディレクトリが認識されない。Claude Codeは~/.claude/agents/.claude/agents/の変更を数秒で検知します。ただし対象は、セッション開始時点で存在していたディレクトリに限られます。あるスコープで初めてagentsディレクトリを作った直後は、セッションを再起動するまで読み込まれません(出典: Claude Code公式ドキュメント)。

つまずき2:toolsのリストが1つも解決できず起動に失敗する。綴りミスや存在しないツール名で、1つも実際のツールに解決できない場合があります。この場合Claude Codeは起動そのものを拒否し、解決できなかった項目名を含むエラーを返します(v2.1.208以降、出典: Claude Code公式ドキュメント)。それより前のバージョンでは、道具ゼロのまま起動し、空や要領を得ない結果を返していました。

つまずき3:並列数が上限に達して追加の起動が失敗する。同時実行上限に達した状態で新しいサブエージェントを起動しようとするとConcurrent subagent limit reachedで失敗します。実行中の数が上限を下回れば再び起動できるようになりますが、リトライすべきではないと公式ドキュメントは明記しています(出典: Claude Code公式ドキュメント)。

3つに共通するのは、画面の上では静かなことです。呼ばれないという結果だけが残り、理由は表示されません。だから最初に確かめるのは書き方ではなく、読み込まれる条件のほうになります。

この章のまとめ

動かない原因の多くは、定義の中身ではなく、読み込みのタイミングと綴りにあります。

14複製したリポジトリでは、サブエージェントの定義ごと消えるんですか?

つまずき4:定義ファイルをGitで追跡していないと、複製したリポジトリでは体制ごと消える.claude/agents/はプロジェクト直下にあるため一見リポジトリの一部ですが、追跡対象に加えていなければ、worktreeやクローンといった同じリポジトリの別の複製には現れません。

「無い」と言う前に、見る場所を替える数えた件数より、数えた場所のほうが効きます「無い」と言う前に、見る場所を替える数えた件数より、数えた場所のほうが効きます複製の中だけで探した手元のコピーを開く一覧に出てこない存在しないと結論づける参照している側の資料は見えているので、疑いにくくなります本体の絶対パスで確かめたリポジトリ本体を開く実体がそこに並んでいる場所とセットで報告する0件は、探した範囲の広さぶんの意味しか持ちません
「無い」と言う前に、見る場所を替える — 数えた件数より、数えた場所のほうが効きます

厄介なのは、追跡済みのファイル(記事や設計書)は複製先にも存在することです。「参照している側は見えるのに、参照されている実装だけが見えない」状態になります。WEBMARKSでは2026-08-03、複製側でls .claude/agents/を実行した検査工程が、実在する3体の定義を「存在しない」と判定しました(社内記録)。

ここから引き出せる読み方は1つです。検索結果が0件であることは、「無い」ではなく「自分が見た場所には無い」しか意味しません。定義ファイルの実在を確かめるときは、複製ではなくリポジトリ本体の絶対パスを見ます。

15AI導入の現場で、サブエージェントが定義どおり動いたとどう確かめますか?

定義ファイルを書いたら、次の4項目で動作を確認します。1つでもズレたら、toolsの綴りとdescriptionの文言を見直します。

  1. 自動委譲を試すdescriptionに合う依頼を自然言語で出す。期待:Claudeがそのサブエージェントへ自動的に委譲する。
  2. 明示呼び出しを試す@でサブエージェント名を指定する。期待:狙った定義が使われ、自動判定を待たない。
  3. 権限の絞り込みを試すtoolsに含めていない操作(例:Writeを渡していないサブエージェントにファイル編集を頼む)を実行させる。期待:その操作を実行できないか、拒否される。
  4. 並列統合を試す:独立した調査を同じ依頼文で並列起動させる。期待:各結果が親の会話へ戻り、ディレクター役がそれらを突合して1つの結論にまとめられる。
動いたと言ってよい画面/まだ言えない画面断られる画面まで見て、はじめて体制になります動いたと言ってよい画面/まだ言えない画面断られる画面まで見て、はじめて体制になります名前を呼んでいないのに、狙った役が出てきた説明欄が効いています名指しすると、その役だけが動いた渡していない操作を頼んだら、断られたここを飛ばすと、絞れていないことに気づけません同時に走らせた結果を、まとめ役が束ねた定義を書いただけで、まだ走らせていない書いた事実しか残っていない状態です
動いたと言ってよい画面/まだ言えない画面 — 断られる画面まで見て、はじめて体制になります

4項目すべてで期待どおりの挙動が出れば、定義ファイルは意図どおりに機能しています。逆に、書いただけの段階では、まだ何も確かめていないことになります。書いた事実と、動いた事実は別に数えます。

3番目だけは、成功ではなく失敗を見にいく確認です。ここを飛ばすと、権限を絞ったつもりで絞れていない状態に気づけません。うまくいく側だけを試して終わりにしないところが、この4項目のねらいです。

この章のまとめ

定義ファイルは、書いた時点ではまだ体制になりません。断られる画面を見たところで、はじめて体制になります。

16よくある質問

サブエージェントとメインの会話は同じ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の基本フィールドは同じです。ただしセキュリティ上の理由から、プラグイン由来のサブエージェントではhooksmcpServerspermissionModeフィールドが無視されます。これらを使いたい場合は、定義ファイルを.claude/agents/~/.claude/agents/へコピーします。優先度もいちばん後ろなので、同じ名前の定義が手元にあればそちらが勝ちます。

toolsとdisallowedToolsは、どちらか片方だけにすべきですか

片方だけでも動きます。両方書くときは、disallowedToolsが先に適用され、残った候補にtoolsが解決される順番だけ覚えておいてください。渡す道具が少ないワーカーはtoolsで列挙するほうが読みやすく、継承した広い権限から特定の操作だけ外したいときはdisallowedToolsが向きます。迷ったら許可リスト側で書いて、渡すものを数え上げられる状態にしておくほうが、後から検査しやすくなります。

17まとめ|今日やる3つのこと

定義ファイルは、能力を足す場所ではなく範囲を削る場所でした。子は親の会話を持っていかないので、渡したいことは指示文に書き出します。そして、書いた定義は動かして断られる画面を見るまで、体制として数えません

今日はこの順で手をつけます

  1. namedescriptionだけの定義ファイルを1つ置いて、名前を呼ばずに委譲されるか試す

    判定に効いているのがdescriptionだと体感できます

  2. toolsからWriteを外したワーカーに、わざとファイル編集を頼む

    断られる画面を見て、はじめて絞れたと言えます

  3. 定義ファイルの実在を、複製ではなくリポジトリ本体の絶対パスで数える

    0件は「無い」ではなく「その場所には無い」しか意味しません

AI検索では、こう聞かれています

  • サブエージェントの定義ファイルには何を書けばいいんですか?

    「サブエージェントを作るとき、AIエージェントの定義ファイルには最低限なにを書けばいいんですか?」の章で説明しています

  • 親の会話の内容は、サブエージェントにも渡るんですか?

    「親の会話や読んだファイルは、サブエージェントにも渡るんですか?」の章で渡る側と渡らない側に分けています

  • サブエージェントは同時にいくつまで走らせられるんですか?

    「サブエージェントを並列で走らせると、どこで頭打ちになるんですか?」の章に上限があります

  • 定義したのに呼ばれないのは何が原因ですか?

    「定義したはずのサブエージェントが動かないのは、なにが原因ですか?」の章で扱っています

次に読むなら、この記事です