Claude Code Subagents完全ガイド — 作り方・無効化・並列実行の設計判断

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

サブエージェントは独立したコンテキストウィンドウで動き、ツール権限とモデルを個別に決められ、複数を並列に走らせられます。サブエージェントを止めたいときは、permissions.deny に Agent を入れれば全面的に、Agent(Explore) のように書けば種類を限って無効にできます(無効化の方法)。本記事は、定義ファイルの書き方から、委譲された側で実際に何が起きるか、権限・モデル・並列の設計判断、つまずきの回避策までを扱います。並列実行の具体パターンは並列実行パターンで深掘りしています。

最小の定義ファイルは2キーで成立する

最小の .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: opus
---
 
# code-reviewer Sub-agent
 
あなたは差分コードの品質ゲート役です。差分のみを 0 ベースで評価します。
 
## レビュー観点(12)
 
1. セキュリティ(秘密情報 / 認証 / SQL インジェクション 等)
2. パフォーマンス(N+1 / 計算量 / メモリ確保)
3. 命名(目的が名前から読み取れるか)
...

tools はカンマ区切りの文字列でもYAMLのリストでも書けます。このほかに任意のキーが並びます。

camelCase の名前は表と完全一致させる必要があり、認識されないキーはエラーなしで無視されます。max_turns や maxTurn と書いても警告は出ません。

ファイルが読み込まれるかを手元で検証する

frontmatterのYAMLが壊れたファイルは、name が読めないため「参照用ドキュメント」扱いで黙ってスキップされます。claude plugin validate にディレクトリを渡すと、このスキップを事前に拾えます(v2.1.233以降)。一時ディレクトリに閉じたYAMLを壊した定義を置いて、v2.1.287で実行した結果が次です。

claude plugin validate .claude/agents

Validating agent: .claude/agents/broken.md
 
✘ Found 1 error:
 
  ❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected EOF. At runtime this agent does not load at all — with no frontmatter name it is treated as a co-located reference document and skipped.
 
✘ Validation failed

name を持たないファイルは、frontmatterが構文として正しければ検査を通ります。v2.1.287では ✔ Validation passed と出ます。委譲が起きないときの切り分けは、このコマンドで構文を見たうえで、同じ name が二重定義されていないか(同一ディレクトリ内の重複はファイルシステムの読み取り順で1つだけが残ります)を /doctor で見る順序になります。

作成経路と配置スコープ

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

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

.claude/agents/ はカレントディレクトリからリポジトリルートまで遡って走査され、入れ子のディレクトリが同名を定義したときはカレントに近い定義が勝ちます。サブフォルダ(agents/review/ など)に分けても、識別は name だけで決まります。

--agents はスクリプトやCIから一時定義するための口で、claude --help には次のように出ます(v2.1.287)。

  --agents <json-or-file>   JSON object defining custom agents, or with --print
                            the path to a file that holds one (e.g. '{"reviewer":
                            {"description": "Reviews code", "prompt": "You are a
                            code reviewer"}}')

ファイルパスを渡せるのは --print(非対話)のときだけで、対話セッションではパスが拒否されます(ファイル形式はv2.1.281以降)。定義が大きすぎてコマンドラインに載らないときの逃げ道です。

--add-dir で追加したディレクトリの .claude/agents/ はプロジェクトのサブエージェントと並んでロードされますが、そこでの追加・編集は監視されず、反映には再起動が要ります。settingsの permissions.additionalDirectories で足した場合はファイルアクセスが付くだけで、サブエージェントはロードされません。プラグイン経由で配布するサブエージェントでは hooks / mcpServers / permissionMode が無視されるため、これらが要るならファイルを .claude/agents/ か ~/.claude/agents/ にコピーします。

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

claude --agent code-reviewer

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

claude agents は別物で、バックグラウンドセッションを一覧管理するagent viewを開きます。--agent / --model / --permission-mode / --effort などは「agent viewから派遣するセッションの既定」を決めるオプションです。

$ claude agents --help
Usage: claude agents [options]
 
Manage background agents
 
Options:
  --agent <agent>         Default agent for sessions dispatched from agent view.
                          Overrides the 'agent' setting.
  --json                  Print active sessions (interactive and background) as a
                          JSON array and exit (for scripting; does not require a TTY)
  --cwd <path>            Show only background sessions started under <path>
  ...

委譲された側では何が起きるか

サブエージェントはメインセッションと別のコンテキストウィンドウで動きます。巨大なコード走査やログ解析をここに任せればメインには要約だけが戻り、レビュー・テスト実行・調査それぞれのシステムプロンプトがメイン会話に混ざることもありません。

通常のサブエージェントの初期コンテキストは、定義本文のシステムプロンプト(Claude Codeのデフォルトプロンプトではなく環境情報が足されたもの)、委譲メッセージ、CLAUDE.md、gitステータス、skills で指定したSkill全文です。Explore と Plan はCLAUDE.mdとgitステータスを読みません。自作のサブエージェントは両方を読むので、「vendor/ は無視する」のような規則はCLAUDE.mdに書いておけば届きます。委譲メッセージに書かせた規則しか要らないなら、omitClaudeMd: true でCLAUDE.mdを外して入力を軽くできます(管理ポリシーのファイルは残ります)。

呼び出し側が渡すべきものは逆に明確です。「現在の変更ファイル」「対象のブランチ」「期待するゴール」は、毎回同じ並びで委譲メッセージの冒頭に置くと安定します。コードレビューなら、変更ファイル・対象ブランチ・見てほしい観点の3点です。渡す情報がぶれると、独立コンテキストの強みが「前提が毎回欠ける」弱点に変わります。

バックグラウンド実行の既定とツールの絞られ方

Claudeが起動するサブエージェントは、対話セッションの既定(フォークモード有効)ではバックグラウンドで走り、Claudeは前景を選べません。非対話の -p とAgent SDKではフォークモードが無効で、結果が必要なときだけ前景になります。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 で常に前景にできます。

バックグラウンドのサブエージェントは、Read / Grep / Glob / Bash / Edit / Write / WebFetch など決まった組み込みツールだけを持ちます。MCPツールは全部使えます。どのサブエージェントからも AskUserQuestion / EnterPlanMode / Workflow などは外れます。権限確認が要るツール呼び出しは、サブエージェント名付きでメインセッションにプロンプトとして上がります。そこで「セッション中ずっと許可」のように1回限りでない回答を選ぶと、その許可はメイン会話を含むセッション全体に効きます。

ツールと権限を絞る

tools は許可リスト、disallowedTools は禁止リストです。両方が書かれているとき、公式の順序は「まず disallowedTools を適用し、残ったプールに対して tools を解決する」で、両方に載ったツールは取り除かれます。tools を省略すると、サブエージェントに使えるツールをすべて継承します。

tools を書いたうえで、同じリストに無いツールを disallowedTools にも書く構成は冗長です。許可リストに載っていないツールはそもそも使えないので、disallowedTools が効くのは「継承したプールから特定ツールを抜く」ときと、「tools に書いたものを個別に取り消す」ときです。MCPは mcp__<server>__* で、サーバー単位に許可・禁止できます。

Bash(git push *) のように引数付きで書いても、disallowedTools ではツール全体が取り除かれる点に注意が要ります。細かい制御はpermissionsルールやhookの領分です。

tools の全エントリが解決できないときは、Claude Codeは起動を拒否して Agent 'code-reviewer' would be spawned with zero tools — refusing. のエラーを返します(v2.1.208以降)。原因は、typo、サブエージェントに使えないツール(バックグラウンドで外れるものを含む)、現セッションに該当ツールが無い(MCPサーバー未接続など)の3種類です。tools を省略した場合や、リストが空になった場合はこの拒否は起きません。直し方は「spawned with zero tools」の対処にまとめています。

permissionModeは親の状態で決まる

permissionMode を省略すると、サブエージェントは親(メイン会話)の権限モードを継承します。指定しても、効くかどうかは親のモード次第です。

フォークは親の権限モードで動き、プランモードから抜けることはできません(v2.1.285以降)。

サブエージェントを無効にする方法

止めたい範囲で書き方が変わります。

種類を限る場合の settings.json は次の形です。括弧内は定義の name と一致させます。

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

設定ファイルを触らず1回だけ止めるなら、CLIで claude --disallowedTools "Agent(Explore)" を渡します。CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 を設定した場合、Claudeは Explore と Plan に委譲せず、ファイルを直接読んで調べます。

モデルの決まり方と軽量モデルへの振り分け

model で実行モデルを指定でき、判定や軽い抽出のように知能負荷が低い処理をHaikuへ流すと、累計トークンコストが下がります。

実際に使われるモデルは、次の順で最初に当たったものになります。

v2.1.251より前は、環境変数が最初に来て呼び出し時のパラメータもフロントマターも上書きしていました。古い解説では順序が逆になっています。環境変数ですべてのサブエージェントを1モデルに固めたいなら、CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 を併せて設定します(v2.1.257以降)。FORCEが有効なあいだは定義の model が無視され、起動時にClaudeがモデルを渡すこともできません。

CLAUDE_CODE_SUBAGENT_MODEL=inherit は未設定と同じ扱いです(v2.1.196以降)。この変数だけでは組み込みの Explore と Plan のモデルは変わらず、変えるには CLAUDE_CODE_SUBAGENT_MODEL_FORCE が要ります。

メインのモデルと同じファミリーのエイリアス(opus など)を指定すると、メインの正確なモデルがそのまま使われます。[1m] 付きなら同じ拡張コンテキストが付きます。また、サブエージェントはメイン会話の拡張思考設定を引き継ぎます(v2.1.198以降)。サブエージェント単位の思考設定はありません。

memoryで知識を永続化する

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

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

MEMORY.md は書き込み自体は成功しても、200行または25KBを超えた分がセッション開始時に読み込まれなくなります。原因と縮め方は「Memory index read limit」の対処にまとめています。

並列実行は「依存しない読み取り」だけに使う

Claude Codeは1つのメッセージで複数のサブエージェントを同時起動できます。メインから呼ぶと、次のようになります。

// メイン agent から複数 sub-agent を並列起動
Agent({ subagent_type: "code-explorer", prompt: "..." })
Agent({ subagent_type: "dependency-checker", prompt: "..." })
Agent({ subagent_type: "doc-researcher", prompt: "..." })

1メッセージに含めた3つは並列に走り、メインには3つの要約が同時に返ります。互いの状態を共有しないので、一方が読んだ内容や途中の推論がもう一方に混ざりません。逆に、前段の出力を後段が前提にする工程や、同じファイルを複数のサブエージェントが書き換える工程は、独立しているがゆえに整合が取れなくなり、直列に倒す対象です。

書き込み競合は直列化以外に isolation: worktree でも避けられます。起動時に一時的なgit worktreeへ作業領域が切り替わり、変更がなければ自動削除、変更が残ればディスクに保持されます。ここで落とし穴になるのは、worktreeが親セッションのHEADではなくデフォルトブランチから分岐する点です。未コミットの作業を前提にするなら worktree.baseRef: "head" を設定します。

同時に走れるサブエージェントは既定で最大20個で、超えると Concurrent subagent limit reached で起動が失敗し、Claudeには再試行しないよう伝わります。CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変更でき、ultracodeが有効なセッションでは上限が適用されません(v2.1.217以降)。数十〜数百のサブエージェントをスクリプトで束ねて検証まで自動で回す規模なら、ダイナミックワークフロー(Dynamic Workflows)が段取りをランタイムに任せる選択肢です。

入れ子の起動は既定で有効で、メイン会話の下に3層まで入れ子にできます。深さの上限に達したサブエージェントからは Agent ツールが外れ、委譲せずに自分で作業して要約を返します。フォークだけは Agent ツールが残り、上限で呼ぶとエラーを返します。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変更でき、1 にすると入れ子を無効化できます。この既定はバージョンで動いてきました。v2.1.172〜v2.1.216は5層で変更不可、v2.1.217〜v2.1.218は1層、v2.1.219から3層です。特定のサブエージェントだけ入れ子起動させたくなければ、定義の tools から Agent を外すか disallowedTools に加えます。Agent(worker, researcher) のカッコ内に型を並べる絞り込みは、claude --agent で主エージェントとして動くときだけ効き、サブエージェントの定義内では型リストが無視されます。

作るべきか、Skillで足りるかを分ける

メイン会話のほうが向くのは、頻繁な往復や反復的な調整が要る作業、計画・実装・テストのようにフェーズ間で多くの文脈を共有する作業、小さな修正、遅延が効く場面です。通常のサブエージェントは白紙から始まるので、文脈集めの時間がかかります。すでに会話にある内容への質問なら、ツールを持たず全文脈を見られる /btw が向きます。

1回限りの調査は、反復して呼び出さないなら都度プロンプトを書くほうが導入コストに見合います。逆に「同じ指示を3回以上ペーストしている」なら自作のシグナルです。

自作には運用負担も伴います。システムプロンプトが詳細なほど、Claude本体や周辺機能のアップデートへの追随が要ります。狭く作りすぎると「結局メインでやったほうが早い」状態になり、呼び出されなくなります。権限は親のモードに引きずられるので、サブエージェント単位で安全側に固めたつもりでも、親が緩ければ緩いままです。

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

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

「現在編集中のファイル」「直前の調査結果」をサブエージェントが読めないのは、コンテキストが独立しているからです。必要な情報は委譲メッセージに明示的に渡します。「Agent({ prompt: "...対象ブランチ: feature/login-fix / 見てほしい観点: 認証まわりの例外処理..." })」のように、毎回フルコンテキストを渡す設計が定石です。

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

Claudeは description を手がかりに「今このサブエージェントを呼ぶか」を判断します。「コードレビューする」のような短い説明では、類似のエージェントが複数あるとき選択がぶれます。「差分コードを12観点でreview、Must / Want / Nitの3段階で指摘」のように、責務・入出力・観点数を1文に込めます。

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

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

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

並列で Edit 系サブエージェントを起動して同じファイルを書かせると競合します。並列にするのは「読み込み + 調査」系に限り、書き込み系は直列にするか isolation: worktree を付けます。たとえば、レビュー役の指摘を受けて修正役が同じファイルを直す構成なら、書き込みは直列にします。複数の情報源を調べる調査役は並列で回せます。

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

サブエージェントの応答だけ見て「何かおかしい」と感じても、トランスクリプトを読まないと因果を追えません。会話画面から素早く開くにはCtrl+Oのトランスクリプトビューアーが使えます。ファイルとして残るのは ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl で、cleanupPeriodDays(既定30日)を過ぎると削除されます。バックグラウンドで完了したサブエージェントは /tasks に30秒間だけ残り、そこからトランスクリプトを開けます。

運用に組み込む手当てとしては、Stop hookで結果を集計ファイルに追記しておく、失敗時に「再現用の最小プロンプト」をメインから渡して確かめる、の2つがあります。

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

システムプロンプトはそのまま入力に乗るので、長大に書くほどサブエージェント側のコンテキストを圧迫します。詳細な参照資料は skills フィールドで外部化するか、memory に蓄積する設計が安全です。

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

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

つまずき8:サブエージェントが「Agent terminated early」で止まる

APIエラーで実行が途中で打ち切られることがあります。フォアグラウンドとバックグラウンドで挙動が異なり再開の手順も変わるので、遭遇したら「Agent terminated early」の対処を参照します。

つまずき9:長時間セッションで会話履歴が壊れtool use/thinking blockが不整合になる

/rewind や /compact を多用したセッションでは、tool useブロックとthinking blockの対応が崩れてエラーになることがあります。表示パターン別の原因と復旧手順はthinking block mismatchエラーの原因とrewindでの直し方にあります。

関連機能との使い分け

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

サブエージェントの定義ファイルはAgent Teamsのteammateとしても流用できますが、tools・model・本文は引き継がれる一方で skills は引き継がれないなど、適用可否がフィールドごとに違います。詳細はAgent Teamsでサブエージェント定義をteammateに流用するで扱っています。

Agent teamsは実験機能で、既定では無効です(環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 で有効化)。teammateを並走させるとトークン消費がサブエージェント単体より膨らみやすく、抑え方はAgent Teamsのコスト管理にまとめています。hooksを含めた4機構全体の判断フローはClaude Code SkillsとMCPの違い — サブエージェント・hooksを含む4機構の使い分けで整理しています。SkillsとSub-agentsの使い分けはClaude Code Skills完全ガイドにもあります。

まとめ

最初は「Read / Grepだけの調査専任エージェント」を1つ作り、claude plugin validate で読み込めることを確かめたうえで、レビューやテスト実行へ広げるのが育てやすい順序です。権限とモデルは定義に書くだけでなく、親のモードと環境変数でどう上書きされるかまで見て設計します。