Claude CodeのSubagents 役割別エージェントの作り方！最小構成から責務分担まで！

監修者_SD以外

監修者プロフィール

森下浩志

日本最大級のAI情報プラットフォーム「romptn ai」編集長。著書に「0からはじめるStable Diffusion」「0からはじめるStable Diffusion モデル・拡張機能集編」など、AmazonベストセラーのAI関連書籍を多数執筆。AIにおける情報の非対称性を解消するための社内研修や出張講義も行う。

Subagents で何が変わるか

Subagents を入れると、Claude Code の作業を「役割ごとに隔離した文脈・最小権限・専用 prompt で動く軽量エージェント」に分割できます。 1 つの会話に全部の指示を積み上げて文脈が汚れたり、CLAUDE.md がレビュー指針もリサーチ手順もテスト規約も抱え込んで肥大化したりする状態から抜け出す仕組みです。

もう 1 つ押さえたいのが、Claude Code 側の仕様がこの 1 年で書き換わっている点です。2026 年 5 月 13 日時点では、以前 Task ツールと呼ばれていた呼び出しが Agent に統一され、Subagent の memory や skills といったフィールドも整備されました。古い記事の「Task(worker)」表記のままだと、責務の置き場所や呼び出し方を読み違えやすくなります。

この記事では『4 レイヤー責務マトリクスを 1 枚で』で全体像を固定したあと、最小 frontmatter で 1 体作り、役割別テンプレで増やし、『事故らない Subagent を組む安全設計』と『作りすぎない運用とコスト感』で締める順番で進めます。

4 レイヤー責務マトリクスを 1 枚で

前章で『役割を分けると文脈が混ざらない』までを押さえました。ここでは Subagent・Skills・CLAUDE.md・Hooks の 4 層を「何が残るか」「いつ動くか」「何をするか」の 3 軸で 1 枚にまとめ、役割をどの層に乗せるか判断できる地図にします。

業務役割もこの軸で翻訳できます。毎回隔離して diff を読ませたいレビューは Subagent、再利用したい調査手順は Skills、守らせたい規約は CLAUDE.md、保存時に走らせたい検査は Hooks に乗せると、責務がもつれません。

なお Slash Commands は 2026 年 5 月 13 日時点で Skills に統合され、独立した呼び出し口としては残っていません。

Subagent の置き場所と作成手順

責務マトリクスで役を決めたら、次は定義ファイルを実際にリポジトリへ置くフェーズです。Subagent は 1 体につき markdown ファイル 1 枚で、置き場所は プロジェクト共有 と 個人用 の 2 種類だけです。

作成経路は 2 つあり、どちらでも結果は同じ markdown ファイルなので好みで選んで構いません。

配置できたら、その場で /agents をもう一度叩いて一覧に <name> が出ているかを確認します。表示されない時はパス・拡張子(.md)・YAML frontmatter のインデント崩れを疑ってください。読み込めていれば、次の章で扱う frontmatter の中身を埋めていく準備は整っています。

frontmatter の最小構成と主要フィールド

置き場所が決まったら、次は md ファイルの先頭に書く frontmatter の中身を決めていきます。frontmatter とは YAML 形式のメタ情報ブロックのことで、ここに何を書くかで Subagent の挙動や呼ばれ方が変わります。

公式 docs を眺めると指定できる項目は十数個に並んでいますが、その全部を最初から書く必要はありません。まずは「これさえあれば立ち上がる」最小の 2 行を固定し、そのあとで「役割に合わせて足すと嬉しい主要 optional」を段階的に積み上げる順番が、迷いを最小にできる進め方です。

この方針に沿って、続く章では最初に最小構成の必須フィールドを押さえ、次に追加で書いておきたい主要 optional の役割を順に見ていきます。

① 必須 2 行 name と description

Subagent の frontmatter は、突き詰めると name と description の 2 行だけで立ち上がります。残りの optional は後から足せるので、まずはこの 2 行を正しく書くことに集中しましょう。

name は親 Claude が識別子として使う ID で、半角英数とハイフンだけで書きます。日本語や大文字混じり (CodeReviewer のような) は読み込まれないため、用途が一目で分かる短い英語をハイフンで繋ぐ形 (code-reviewer / test-writer など) が安全です。

---
name: code-reviewer
description: PR レビュー時や、コード差分がコミットされた直後に呼び出してください。読み取り中心でバグ・命名・設計上の懸念を指摘します。
---

description で大事なのは、capability(何ができるか)ではなく trigger conditions(いつ呼ばれるべきか) を書くことです。親 Claude はこの文面を読んで自動委任の可否を判断するため、コードをレビューする のような能力説明だけだと発火条件にならず、想定通りに呼ばれません。

「PR レビュー時」「差分がコミットされた直後」のように、呼んでほしい場面を具体的な日本語の合図として書くのがコツです。良い例と悪い例の詳しい対比は、後ほどの『自動委任と @ メンションでの呼び出し方』の章で扱います。

② 主要 optional の使いどころ

name と description で動かしたあと、最小構成に上から足すと効きやすいのが次の 6 つです。網羅ではなく「役割を絞った Subagent に必要十分」という観点で選んでいます。

tools の最小権限の決め方と isolation の事故防止は、後ほどの「事故らない Subagent を組む安全設計」の章でまとめて深掘りします。ここではまず、役割に直結するものから 1〜2 個ずつ書き足していけば十分です。

自動委任と @ メンションでの呼び出し方

frontmatter を作り終えたら、次は Subagent をどう呼び出すかです。

呼び出し経路は 親 Claude による自動委任 と、ユーザーが @<name> で指名する 明示呼び出し の 2 つです。明示呼び出しは確実に当てに行ける手段なので、まずはこちらで動作確認するのが安全です。自動委任は親 Claude が会話の流れから委任先を選ぶ仕組みで、その判断材料は frontmatter の description だけです。

ここで効くのが書き方の方針です。description は 「何ができるか」ではなく「いつ呼ばれるべきか」 を書きます。能力リストだけだと、親はどの場面で渡せばよいか決められず、必要な場面で呼ばれない・無関係な場面で発火するといったズレが起きます。

書き換えのコツは、冒頭を Use this agent when ... のように いつ呼ぶかから始める ことです。対象の状況(差分が出た直後・特定ファイルを編集した直後など)を 1〜2 文で具体化し、能力の説明は最小限にとどめます。

もう 1 点、設計上の制約として ファンアウトは 1 段まで を押さえておきます。親 Claude は複数の Subagent を順に呼べますが、呼ばれた Subagent から別の Subagent を連鎖呼び出しすることはできません。調査担当の結果をレビュー担当へ自動で渡したい場合は、親 Claude が両方を順に呼ぶ設計に整理します。

役割別テンプレートで最初の 3 体

ここからは、前の章で扱った「いつ呼ばれるか」を実際の Subagent ファイルに落とし込みます。最初に置く 3 体は、コードレビュー・リサーチ・テスト生成の 3 役割です。役割の輪郭がはっきりしていて、責務マトリクス上の住み分けもしやすく、書き込み権限の絞り方や isolation の効かせどころが対照的なため、最初の 3 体としてバランスが良い組み合わせになります。

以降の各テンプレートは、最小の frontmatter とシステムプロンプトの骨格だけを示し、責務マトリクス上のどこに置くか、そして description を「いつ呼ばれるべきか」の形で書く時にどんな表現が効くかを併記する形でまとめています。tools と isolation の細かな絞り込みは後ほどの『事故らない Subagent を組む安全設計』の章でまとめて扱うので、ここではまず役割ごとの輪郭を掴むつもりで読んでください。

もっと多くの役割例を眺めたい場合は、外部の踏み台コレクション awesome-claude-code-subagents（VoltAgent 公開）にカテゴリ別の Subagent サンプルがまとまっています。自分のチーム業務に近いものを見つけたら、frontmatter とシステムプロンプトを最小に削ってから取り込むと、責務の境界を保ったまま流用しやすくなります。

① コードレビュー Subagent

最初に置くなら、書き込みを一切させないレビュー専任の 1 体です。コードの差分（diff）を読んで、設計上の懸念・バグ・命名の違和感を指摘して戻すところまでが仕事で、ファイルの修正は親側に任せます。

以下が最小テンプレートです。tools を Read, Grep, Glob に絞ることで、レビュー中に勝手にコードを書き換える事故を物理的に止めています。

---
name: code-reviewer
description: PR レビュー時、または会話中に新しいコード差分が貼られた直後に呼び出す。設計・バグ・命名の観点で指摘を返す。書き込みは行わない。
tools: Read, Grep, Glob
model: sonnet
---

あなたはコードレビュー担当です。渡された差分を読み、次の 3 点を返してください。

- 設計上の懸念（責務の漏れ・依存方向の逆転など）
- 想定バグ・エッジケース
- 命名や可読性で直したい箇所

コードの修正案は提案にとどめ、ファイルの書き換えは行いません。

ポイントは description をいつ呼ばれるべきかで書いている点です。「コードレビューができます」のような能力説明ではなく、「PR レビュー時」「差分が貼られた直後」といった発火条件を入れておくと、親 Claude が自動で投げてくれる確率が上がります。

② リサーチ Subagent

公式 docs を横断して読み込み、結果を構造化レポートで親に返すのがリサーチ Subagent の責務です。責務マトリクスでは「調査レイヤー」に位置し、後段の設計・実装に引き渡す素材を作るのが役割になります。書き込みは一切させず、読みと外部取得だけに権限を絞るのが安全側の既定です。

tools は Read と WebFetch を中核にし、Edit / Write / Bash は外します。こうすると親側の意図しないリファクタやコミットが走る事故を物理的に止められます。memory: project を付けると、参照した URL や読み込んだファイルが調査ログとしてプロジェクトに蓄積され、次回の調査でも引き継げます。

---
name: researcher
description: 新しいライブラリやAPI仕様を調査する時、複数docsを横断して比較する時に呼ぶ。実装やリファクタは扱わない。
tools:
  - Read
  - WebFetch
memory: project
model: sonnet
maxTurns: 12
---
あなたは調査担当です。指示された論点について公式 docs を一次資料として確認し、出典 URL・該当箇所・要点を箇条書きで返してください。コードの修正提案は行いません。

description の trigger conditions は「実装やリファクタは扱わない」のように呼ばれない場面まで明示するのがポイントです。これを書かないと、コード修正の流れの中で勝手に発火して調査だけで止まる、という想定外の挙動につながります。tools 最小権限の詳しい考え方は後ほどの『tools は最小権限から始める』の章で扱います。

③ テスト生成 Subagent

3 体目は、対象コードを読んでユニットテストの雛形を書き出す役割です。レビュー専任とは違って Edit と Write を解禁しますが、書く先はテストディレクトリだけに限定し、さらに isolation: worktree で実行環境ごと現在のブランチから切り離します。

以下が最小テンプレートです。tools は実装本体を読むための Read と、テストファイルを置くための Edit / Write までで止め、書き込み先の制約はシステムプロンプト側で明文化しています。

---
name: test-writer
description: 新しい関数やクラスが追加された直後、またはテストが不足しているコードに対してユニットテストの雛形を生成する。実装本体は書き換えない。
tools: Read, Edit, Write, Grep, Glob
model: sonnet
isolation: worktree
---

あなたはユニットテストの雛形を書く担当です。渡されたコードを読み、次の手順で進めてください。

- 編集して良いのは `tests/` / `test/` / `__tests__/` 配下のみ。実装ファイル本体は書き換えない
- 正常系・異常系・境界値の 3 観点でテストケースを並べる
- 既存のテストフレームワーク（jest / vitest / pytest など）に合わせる

判断に迷う場合はテストを書かず、必要な前提を質問として返します。

ポイントは 2 つあります。1 つ目は、tools で Edit / Write を渡しているのに書き込み先はシステムプロンプトで縛る形にしている点です。tools フィールド自体はパス単位での絞り込みを持たないため、ディレクトリ制約は指示文で明示するのが現実的な書き方になります。

2 つ目は isolation: worktree を入れている点で、これにより別の git worktree でテスト生成が走り、雛形が走り書きされた場合でも現在のブランチに影響しません。worktree を効かせる根拠と、向く役割・向かない役割の判断基準は、後ほどの『isolation で実行環境を分ける』の章でまとめて扱います。

事故らない Subagent を組む安全設計

ここまでで役割別テンプレートが揃いましたが、テンプレを置くだけでは事故は防げません。レビュー専任のはずが勝手にコードを書き換えてしまったり、テスト生成中に現作業ツリーへ破壊的な変更が走ったり、長尺ループに入ってトークンを浪費する、といった事故は実際に報告されています。

原因の多くは、tools を絞らず親の権限をそのまま継承させていたり、isolation を指定せず現在の作業ツリーで動かしていたりといった、初期設定の油断にあります。テンプレが期待どおり動くかは、frontmatter にどの安全弁を書き込んでおくかで決まると考えてください。

ここからは、事故を未然に止めるための 3 つの観点を順に整理していきます。tools の最小権限、isolation による実行環境の分離、そして maxTurns による暴走停止の 3 つです。それぞれの考え方と書き分けの目安を、後ほどの章で詳しく見ていきます。

① tools は最小権限から始める

frontmatter で tools を書かないと、その Subagent は親 Claude が持つ tool 権限をそのまま引き継ぎます。レビュー専任のつもりで作ったはずなのに、親が Edit / Write を持っていれば子も書ける、という状態が既定です。

そこで設計の起点は「全部入りから削る」ではなく、Read だけを許可してから必要な tool を足していく引き算にします。読むだけで仕事が終わる役割なら、書き込み系の tool は一切載せません。

例えばコードレビュー Subagent の frontmatter は、最初はこの程度まで絞れます。

name: code-reviewer
description: PR の diff が出た直後にレビュー観点で読む。
tools: Read, Grep, Glob

② isolation で実行環境を分ける

前項の tools が「何を触れるか」の壁だとすれば、isolation は「どこで触るか」の壁です。isolation: worktree を指定すると、Subagent は git worktree を切った別ディレクトリで動き、現在開いている作業ツリーには手を入れません。

指定を省くと既定では現作業ツリーがそのまま使われます。書き込み権限を持った Subagent が走った瞬間に、レビュー中のファイルや未コミットの変更が上書きされる事故はこの設定漏れから起きます。

向くのは、ファイル生成や広範な書き換えを伴う役割です。テストコードの自動生成や、大規模リファクタを任せる Subagent は、別ツリーに隔離して走らせ、差分が安全だと確認してから本体に取り込みます。

一方、tools が Read だけのレビュー専任のように書き込みが発生しない役割では、worktree を切る I/O コストが体感の遅さに直結するため、isolation は外したままで構いません。役割の出力先で切り替える、と覚えてください。

③ maxTurns で暴走を止める

ループの上限を明示しないと、Subagent は自己修正や再確認を繰り返したまま会話ターンを消費し続けます。気付いた時には数十ターン分のトークンを使い切っていた、という事故はここから生まれます。

対策はシンプルで、Subagent ごとに「これ以上は止める」という上限ターン数を決めておくことです。役割によって妥当な値は変わるので、目安は次のように整理できます。

上限値そのものよりも、「役割の重さに対して短すぎず、暴走を許すほど長くもない」帯に収めることが重要です。迷ったら短めから始め、途中で打ち切られるようなら少しずつ伸ばす運用が安全です。

ここまでの安全設計を振り返ると、tools を最小権限から始める、isolation で実行環境を分ける、そしてループの上限ターンを決める、という 3 点を組み合わせるのが基本です。どれか 1 つだけでは事故は防ぎきれず、3 つを揃えて初めて「壊れても被害が限定される Subagent」になります。

権限継承と Explore-Plan-Code

ここからは安全設計の続きで、見落としやすい 2 点を整理します。

まず権限継承です。親セッションの permissionMode が auto / bypassPermissions / acceptEdits のいずれかで動いている場合、子 Subagent 側の frontmatter で別モードを書いても override できず、親の運用モードを引き継ぎます。

対策はシンプルで、危険な操作を含み得る Subagent を呼ぶ前に親側を既定モードへ戻すか、tools 自体を Read 系のみに削ぐことです。frontmatter で守るのではなく、親側と tools で守る、と覚えるのが安全です。

次に Explore-Plan-Code パイプラインです。これは Anthropic 公式が紹介している『調査 → 設計 → 実装』を分けて回す進め方で、3 段それぞれに別の Subagent を割り当てると相性が良くなります。

責務マトリクスで決めた境界に沿って 3 段を回すと、文脈汚染も書き込み事故も発生源を切り分けやすくなります。

作りすぎない運用とコスト感

ここまで組み立て方と呼び出し方を見てきましたが、次の悩みは「結局、何体まで作っていいのか」という運用感です。

Subagent は 1 体ごとに専用の文脈と prompt を抱えるため、体数が増えるほどトークン消費はじわじわと膨らみます。日本語コミュニティでは「役割を分けたくて 10 体以上量産したら Pro のレートが厳しく、Max への移行を検討した」という声も報告されています。個別事例ですが、設計の早い段階で意識しておく価値はあります。

おすすめは、まず 1〜2 体から始めるやり方です。最初はレビュー専任やリサーチ専任など責務が明確なものだけを置き、運用で「ここは別文脈で動かしたい」と詰まった時に足す引き算で組みます。

ゼロから書く必要もなく、awesome-claude-code-subagents のような公開コレクションを踏み台にできます。役割別テンプレートを拾い、frontmatter と prompt を調整するだけで短時間で立ち上がります。

なお Pro / Max プランごとの料金体系や使用量上限については、別記事で詳しく扱っています。

よくある質問

Subagent 設計のまとめ

ここまで、Subagent を設計するための地図を一枚にまとめてきました。最後に全体の流れを短く振り返り、今日から動かすための次の一歩を示します。

本記事で扱った要点は次のとおりです。

次の一歩はシンプルです。まずレビュー専任 Subagent を 1 体だけ .claude/agents/ に置き、@reviewer で呼び出す手触りを確かめてください。テンプレが思いつかない場合は、コミュニティ製のコレクション awesome-claude-code-subagents を踏み台にすると早いです。

Subagent は増やすほど強くなる仕組みではなく、責務が分かれているほど効く仕組みです。1 体を回し切ってから次を足す、という順番で組めば、コストも事故も小さく抑えられます。