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 で禁止リスト、Agent(agent_type) で他エージェント呼び出しの範囲も指定可能
• モデル選択ができる: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の主要キーは次のとおりです。

独立コンテキストの意味

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では微妙な独自性 / キュレーション感の判定でブレが出ます。

並列実行パターン

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並列実行パターンで扱っています。

メインから手動で並列起動できるのは数個までです。数十〜数百のサブエージェントをスクリプトで束ね、検証まで含めて自動で回す規模になると、ダイナミックワークフロー(Dynamic Workflows)がランタイムに段取りを任せる選択肢になります。

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

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

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

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

つまずき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が他Sub-agentを呼べると思っている

tools にAgentを含めない限り、sub-agentは他sub-agentを呼べません。sub-agentの定義で tools に Agent を入れると、そのsub-agentは入れ子のsub-agentを起動できます(Claude Code v2.1.172以降)。一方で 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 は並列、のように使い分けています。

まとめ

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

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

具体的な作り方はサブエージェントの作り方で5つの観点(コンテキスト分離 / 役割固定 / ツール制限 / コスト最適化 / 再利用)から扱い、並列実行の具体パターンはSub-agent並列実行パターンで扱っています。SkillsとSub-agentsの使い分けはClaude Code Skills完全ガイドで詳しく説明しています。

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