Claude Code Sub-agents完全ガイド — 独立コンテキストと並列実行の設計判断

Claude Code Sub-agentsは .claude/agents/<name>.md を1つ置くだけで、独自のサブエージェントを定義する仕組みです。ビルトインの汎用エージェント(general-purpose / Explore / Plan 等)に加え、コードレビュー専任 / DB読込専任 / 記事採点専任のように責務を絞ったエージェントを自作できます。

本記事では作り方・フロントマター仕様・独立コンテキスト・ツール制限・軽量モデルルーティング・並列実行の設計判断、メリットとコスト、よくあるつまずきと回避策までをまとめます。並列実行の具体パターンは並列実行パターンで深掘りしています。

Claude Code Sub-agentsとは

• .claude/agents/<name>.md を1つ置けば、独自のサブエージェントが成立する最小構成
• frontmatterで name / description / tools / model を指定、本文はMarkdownのシステムプロンプト
• 独立コンテキストで動く:メインセッションのコンテキストを汚さず、結果サマリだけを返す
• ツール制限ができる:tools で許可リスト、disallowedTools で禁止リストを指定可能
• モデル選択ができる:model: haiku のように軽量モデルにルーティング、累計トークン消費を抑えられる
• 並列実行ができる:メインから複数sub-agentを同時起動して、独立に走らせる

CLAUDE.md(プロジェクト全体の常駐ルール)・Skills(手順書 / 判断基準のファイル化)・MCP(外部システム連携)との使い分けは、後半の「関連機能との使い分け」で扱います。

最小構造

最小の .claude/agents/<name>.md は次のような形です。frontmatterの name と description だけが必須です。

---
name: code-reviewer
description: 差分コードを 12 観点(セキュリティ / パフォーマンス / 命名 / テスト カバレッジ等)で review する sub-agent。Must / Want / Nit の 3 段階で指摘を返す。
tools:
  - Read
  - Grep
  - Bash
disallowedTools:
  - Write
  - Edit
model: claude-opus-4-8
---
 
# code-reviewer Sub-agent
 
あなたは差分コードの品質ゲート役です。`reviewer` と異なり差分のみを 0 ベースで評価します。
 
## 採点観点(12)
 
1. セキュリティ(秘密情報 / 認証 / SQL インジェクション 等)
2. パフォーマンス(N+1 / 計算量 / メモリ確保)
3. 命名(目的が名前から読み取れるか)
...

frontmatterの主要キーは次のとおりです。

作成方法とスコープ

.claude/agents/<name>.md を直接書く以外にも作成経路があります。

もっとも手早いのは、Claude自身に「コードレビュー専任のサブエージェントを作って」と頼んで .claude/agents/<name>.md を書かせる方法です(公式Quickstartもこの経路を案内しています)。生成されたファイルを直接編集して調整します。Claude Codeは ~/.claude/agents/ と .claude/agents/ を監視しており、ファイルを追加・編集すると数秒で検知され、次の委譲から新しい定義が使われます(再起動不要。セッション開始時に存在しなかった agents ディレクトリを新規作成した場合は再起動が要ります)。なお /agents コマンドの対話ウィザードはv2.1.198で廃止され、現在は直接編集を促す案内が表示されるだけです。

個別に委任するのではなく、セッション全体をそのサブエージェントとして起動する --agent というモードもあります。

claude --agent code-reviewer

このときサブエージェント定義のシステムプロンプトがClaude Codeのデフォルトシステムプロンプトに置き換わり、tools / model 制限もセッション全体に適用されます。プロジェクトのデフォルトとして固定したい場合は .claude/settings.json に {"agent": "code-reviewer"} を書きます(CLIフラグの方が優先)。プラグイン提供のサブエージェントも名前だけで解決でき、同名が衝突する場合のみ claude --agent <plugin-name>:<agent-name> のようにスコープ付き名で曖昧さを解消します。

ファイル配置でスコープが決まり、同名で衝突すると優先度の高い場所が勝ちます。

プロジェクト用のサブエージェントは .claude/agents/ に置いてgit管理するのがチーム共有の基本形です。--add-dir で追加したディレクトリの .claude/agents/ はプロジェクトのサブエージェントと並んでロードされます。一方、settingsの permissions.additionalDirectories で追加した場合はファイルアクセスが付くだけでサブエージェントはロードされない、という違いがあります。プラグイン経由で配布する場合は hooks / mcpServers / permissionMode フィールドがセキュリティ仕様として無視されるため、これらを使いたければプラグイン提供のファイルを .claude/agents/ か ~/.claude/agents/ にコピーするか、permissions.allow を settings.json 側で明示します。

フロントマター仕様の全体像

最小構造で挙げた5キー(name / description / tools / disallowedTools / model)以外にも、公式が定義しているフィールドがあります。name と description 以外はすべて任意です。

このうち model の解決順序・memory・isolation は設計判断に直結するため、後段で個別に扱います。

独立コンテキストの意味

Sub-agentはメインセッションと完全に別のコンテキストウィンドウで動きます。これは強力な性質で、次のような効果が得られます。

ただし注意点もあります。Sub-agentはメインのコンテキストを参照できないため、必要な情報は呼び出し側がpromptに明示的に渡す必要があります。「現在の変更ファイル」「対象のslug」「目的」を毎回引数として書く設計が定石です。

引数設計は呼び出し側の責務として、最初から型を決めて固定しておくと安定します。記事パイプラインであれば、対象記事のslug・いま編集しているh2見出し・そのsub-agentに期待するゴール(採点なのか書き直しなのか)の3点を、毎回同じ並びでpromptの冒頭に置く形が扱いやすいでしょう。呼び出すたびに渡す情報がぶれると、独立コンテキストである強みが逆に「前提が毎回欠ける」弱点に変わります。受け取り側が何を読めば作業を始められるかを先に決め、その項目を呼び出し側のテンプレートに落とし込んでおくと、メインを汚さずに必要な文脈だけを渡せます。

ツール制限の設計

tools と disallowedTools の組合せで、各sub-agentに与える権限を最小化できます。

両者の優先関係はあらかじめ押さえておくと設計がぶれません。tools を省略するとsub-agentはメインから継承した全ツールを使え、tools を書くとその許可リストに載ったツールだけに絞られます。disallowedTools は、継承または tools で指定した範囲から特定のツールを取り消す指定です。つまり許可と禁止が重なったときは禁止が勝つ動きになり、「tools で読み込み系をまとめて許可しつつ、disallowedTools で一部だけ確実に塞ぐ」という二段構えの絞り込みができます。よくあるパターンは次のとおりです。

いずれの構成でも、まず tools で「このsub-agentが触ってよい範囲」を決め、その内側で disallowedTools を使って取り消したいツールだけを名指しする順序で考えると整理しやすいでしょう。「最小権限の原則」をSub-agent単位で機械的に効かせられるのが、Skillとは異なる強みです。Skillは呼び出し側のコンテキスト権限で動きますが、Sub-agentは自前の権限境界を持ちます。

モデル選択の経済性

Sub-agentは model で実行モデルを指定できます。「判定」「軽い調査」のような知能負荷の低い処理はHaikuに流すと、累計トークンコストが大きく減ります。

注意点として、判定基準が複雑な採点(本サイトの quality-judge のような4観点採点 + ゼロトレランス禁則)はOpusが安全です。Haikuでは微妙な独自性 / キュレーション感の判定でブレが出ます。

model は次の優先順位で解決されます。「定義ではHaikuなのにテスト時だけSonnetで動かしたい」といった一時的な上書きは、この順序のどこを変えるかで決まります。

1. CLAUDE_CODE_SUBAGENT_MODEL 環境変数
2. 呼び出し時のper-invocation model パラメータ
3. サブエージェント定義の model フロントマター
4. メイン会話のモデル(デフォルト)

memoryで知識を永続化する

memory: project を指定すると .claude/agent-memory/<name>/ に、会話を跨いで保持される知識を蓄積できます。レビュー専任エージェントなら「過去に見つけたバグのパターン」や「このプロジェクトの命名規則」を MEMORY.md に蓄積でき、次回起動時に冒頭200行(または25KB)が自動でcontextに注入されます。

project が推奨のデフォルトです。チームで共有したい知識はgitに乗せ、個人スクラッチパッドは local を選びます。

並列実行パターン

Claude Codeは1つのメッセージで複数のSub-agentを同時起動できます。これは性能・スループット両面で大きな効果を生みます。

// メイン agent から複数 sub-agent を並列起動
Agent({ subagent_type: "explore-sources", prompt: "..." })
Agent({ subagent_type: "competitive-analyzer", prompt: "..." })
Agent({ subagent_type: "keyword-strategy-researcher", prompt: "..." })

上記を1メッセージに含めると3つが並列実行され、メインに3つの要約が同時に返ります。シリアル実行に比べて2〜3倍速くなることが多く、独立調査タスクには特に効きます。

並列実行が安全に成立するのは、各sub-agentが独立したコンテキストで動き、互いの状態を共有しないからです。一方が読み込んだ内容や途中の推論がもう一方に混ざらないため、同時に走らせても片方の作業が他方の前提を書き換えてしまう事故が起きません。編集の視点で言い換えると、「結果が互いに依存せず、同じ資源を奪い合わない」タスクに絞れば並列化の旨味だけを取れる、ということです。逆に前段の出力を後段が前提にする工程や、同じファイルを複数のsub-agentが書き換える工程は、独立しているがゆえに整合が取れなくなるので直列に倒すのが無難でしょう。

並列実行が向くケースと向かないケースは次のとおりです。

同じファイルを複数のsub-agentが編集する可能性がある場合は、直列化以外に isolation: worktree という選択肢もあります。指定すると起動時に一時的なgit worktreeへ作業領域が切り替わり、並列実行のまま書き込み競合を避けられます。メインに自動で返るのは要約だけで、変更が残ったworktreeはディスク上に保持されます(何も変更しなければ自動削除)。また既定では親セッションのHEADではなくデフォルトブランチから分岐するため、未コミットの作業を前提にする場合は worktree.baseRef: "head" の指定が要ります。

詳細パターンはSub-agent並列実行パターンで扱っています。

同時に走れるsub-agentは既定で最大20個です(CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変更可)。数十〜数百のサブエージェントをスクリプトで束ね、検証まで含めて自動で回す規模になると、ダイナミックワークフロー(Dynamic Workflows)がランタイムに段取りを任せる選択肢になります。

いつSub-agentを作るか — 判断早見表

「この機能にはSub-agentを作るべきか、Skillで十分か、CLAUDE.mdに書くべきか」を、状況別の推奨レイヤーで対応付けます。

次の3つは、作るとかえって遠回りになりやすいケースです。

• 進行を逐次見ながら調整したい対話的な作業:サブエージェントはメインから見るとブラックボックスなので、経過を見ながら軌道修正したい用途とは相性が悪く、メイン会話で進めたほうが速いことが多いです
• 分岐が多すぎる総合タスク:専門化しきれず破綻しやすいので、責務を絞れる単位に分割してから検討します
• 1回限りの調査:反復して呼び出さないなら、都度プロンプトを書くほうが導入コストに見合います

逆に「同じ指示を3回以上ペーストしている」は自作の最大シグナルです。

自作のコストも見ておく

独立コンテキスト・ツール制限・モデル選択という利点の裏返しとして、運用上の負担も発生します。

• メンテナンスコスト:システムプロンプトが詳細であるほど、Claude本体や周辺機能(Skills / MCP)のアップデートに追随するメンテが必要になります
• デバッグの難しさ:メインに返るのは要約だけなので、内部の挙動を追うには追加の手当てが必要です(具体策はつまずき7で扱います)
• 過剰な特化の罠:狭く作りすぎると「結局メインで自分でやった方が早い」状態になり、呼び出されなくなります
• 権限設計の責任:bypassPermissions を不用意に付けるとsub-agent側で .git / .claude 等への書き込みが通ります。自由度と安全性のトレードオフを毎回意識する必要があります

よくあるつまずきと回避策

Sub-agentsの運用で踏みやすい落とし穴を10件集めました。

つまずき1:メインの変数 / 状態がsub-agentに渡らない

「現在編集中のファイル」「直前の調査結果」をsub-agentが読めないのは、コンテキストが独立しているからです。必要な情報は呼び出し側のpromptに明示的に渡します。「Agent({ prompt: "...対象 slug: claude-code-hooks-guide / 編集中の h2: 設定ファイルの構造..." })」のように、毎回フルcontextを渡す設計が定石です。

つまずき2:description が抽象的で自動選択がブレる

Claudeはdescriptionだけを読んで「今このsub-agentを呼ぶべきか」を判断します。「コードレビューする」のような短い説明では類似のagentが複数あるとき選択がぶれます。「差分コードを12観点(セキュリティ / パフォーマンス / 命名 / テストカバレッジ等)でreview、Must / Want / Nitの3段階で指摘」のように、責務 / 入出力 / 観点数を1文に込めます。

つまずき3:tools 指定漏れで「使いたいツールが使えない」

tools を指定すると、その許可リストに書かれていないツールは使えなくなります。例えば tools: [Read] だけ書いてBashを許可しないと、bashを要する処理が動きません。「読み込み + 検索」が必要なら tools: [Read, Grep, Glob] のように展開して書きます。指定しなければ全ツールが許可されますが、安全側で明示するのが推奨です。

つまずき4:入れ子のSub-agent起動は「既定でオン」

サブエージェントは既定で自分のサブエージェントを起動でき、メイン会話の下に3階層まで入れ子にできます(上限は CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変更でき、1 にすると入れ子を無効化できます)。深さの上限に達したサブエージェントからは Agent ツールが自動的に外され、委譲せず自分で作業して要約を返します。特定のサブエージェントだけ入れ子起動させたくない場合は、その定義の tools から Agent を外すか disallowedTools に加えます。一方で Agent(agent_type) のカッコ内に書く型リストによる絞り込みは、claude --agent でメインスレッドとして動く場合にのみ効きます。sub-agentの定義内ではカッコ内の型リストは無視されるため、起動できるsub-agentの種類を定義側で限定する用途には使えません。

つまずき5:Haikuに重い思考を投げて精度が崩れる

「採点」「独自性判定」「キュレーション感検出」のような微妙な判断はHaikuでは精度が出ません。判定軸が明文化されており、機械的判断で済む場合のみHaikuでOKです。複雑な独自性採点はOpusを使い、コスト最適化は単純抽出系のsub-agentに絞ります。

つまずき6:並列実行で同じファイルに同時書き込みして競合

並列で Edit 系sub-agentを起動して、同じファイルを書き込ませると競合します。並列にするのは「読み込み + 調査」系に限り、書き込み系は直列実行にします。本サイトでは quality-judge 採点後の rewriter 書き込みは直列、explore-sources / competitive-analyzer / keyword-strategy-researcher は並列、のように使い分けています。

つまずき7:中身が見えない箱で挙動を追えない

サブエージェントの応答だけ見て「何かおかしい」と感じても、transcriptを読まないと因果を追えません。デバッグのために以下を運用に組み込みます。

• ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl を時々開く
• Stop hookで結果を集計ファイルに追記しておく
• 失敗時に「再現用の最小プロンプト」をメインから渡してチェックする

つまずき8:システムプロンプトが長大すぎる

サブエージェントは独立contextで動きますが、システムプロンプト自体がそのまま入力に乗るため、長大に書くほどサブエージェント側のcontextを圧迫します。公式がSKILL.mdに対して推奨する「500行以内」の感覚を目安に、詳細な参照資料は skills フィールドで外部化するか、memory に蓄積する設計が安全です。

つまずき9:bypassPermissions 乱用

ツール承認を全部スキップする bypassPermissions は便利ですが、.git / .claude / .vscode 等への書き込みも通ります。利用するときは「信頼済みの作業領域に閉じている」「isolation: worktree 併用」の2条件を意識します。

なお、親(メイン会話)が bypassPermissions / acceptEdits を有効化していると、子サブエージェントの permissionMode 指定は無視されて親モードが継承されます。親が auto モードの場合も子の permissionMode は効かず、ツール呼び出しは親の分類器でチェックされます。サブエージェント側で安全側に倒したいと思っても、親モードが緩いと意図通りには絞れない仕様です。

つまずき10:別サブエージェントとの責務重複

「コードレビュー」「コードの品質判定」「コードの改善提案」のように似た役割を別ファイルで持ってしまうと、Claudeが委任先を判断できず精度が落ちます。1つのサブエージェントに1つの焦点を徹底し、責務が増えてきたら専門ごとに分割するのが運用上のセオリーです。

関連機能との使い分け

サブエージェントは「セッション内で動く専門ワーカー」ですが、似た目的の機能が他にもあります。

Agent teamsは実験機能で、既定では無効です(環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 で有効化)。

「自走させたい / contextを汚したくない / 権限を制限したい」ならサブエージェント、「毎回同じ手順を呼びたい」ならSkills、「常に効いている前提情報を持たせたい」ならCLAUDE.md、という棲み分けが基本です。

まとめ

Claude Code Sub-agentsは「独立コンテキスト」「ツール制限」「モデル選択」「並列実行」の4つの強みを組み合わせるレイヤーです。設計判断の軸は次の3つです。

1. コンテキストを分けたい / ツール権限を絞りたい / 軽量モデルで走らせたい → Sub-agent
2. メインの会話文脈で完結する手順書 → Skill
3. プロジェクト全体に常駐するルール → CLAUDE.md

並列実行の具体パターンはSub-agent並列実行パターンで扱っています。SkillsとSub-agentsの使い分けはClaude Code Skills完全ガイドで詳しく説明しています。

Sub-agentsは導入の初期コストはやや高めですが、いったん運用に乗ると「メインを汚さない調査」「権限境界が機械的に効く設計」が継続的に効く投資効果の良い領域です。最初は「Read / Grepだけの調査専任agent」から始め、慣れたらレビュー / 採点 / オーケストレーションへ展開する形が安定して育てやすいでしょう。