本文へスキップ
Claude Media
Claude Code Sub-agents完全ガイド — 独立コンテキストと並列実行の設計判断
Claude Code解説

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

Claude Code Sub-agentsは .claude/agents/<name>.md で独自のサブエージェントを定義する仕組みです。独立コンテキスト、ツール制限、軽量モデルルーティング、並列実行の設計判断、よくあるつまずきまでを完全網羅します。

読了目安 約12分

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

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

キー役割必須
nameSub-agent識別子。Agent({ subagent_type: "<name>" }) で呼ぶ✓
description用途を1文で。Claudeが文脈から自動選択する時の手がかり✓
tools許可するツール一覧(Read / Edit / Write / Bash / Grep / WebFetch等)—
disallowedTools禁止するツール一覧。tools で許可した中から特定ツールを取り消す—
model使用モデル。haiku / sonnet / opus から選択(コスト最適化に有効)—

独立コンテキストの意味

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

効果説明
メインのトークン残量を温存巨大なコード走査・ログ解析をsub-agentに任せ、メインには要約だけ返す
プロンプト汚染を防ぐ専門領域(レビュー / 採点 / 調査)のsystem promptがメイン会話に漏れない
並列実行が安全互いに独立しているので、3つのsub-agentを同時起動しても干渉しない

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

ツール制限の設計

tools と disallowedTools の組合せで、各sub-agentに与える権限を最小化できます。よくあるパターンは次のとおりです。

Sub-agentの責務推奨ツール構成理由
調査・読込専任tools: [Read, Grep, Glob, WebFetch] + disallowedTools: [Edit, Write, Bash]副作用ゼロで安全。誤って書き込み事故を起こさない
コードレビューtools: [Read, Grep, Bash] + disallowedTools: [Edit, Write]読み + テスト実行は可、書き込み禁止
ドラフト執筆tools: [Read, Edit, Write]ファイル生成のためWrite必須
採点・判定tools: [Read, Grep] + disallowedTools: [Bash, Edit, Write, WebFetch]読み込みのみ、副作用ゼロで純粋な判定
Web検索専任tools: [WebFetch, WebSearch, Read] + disallowedTools: [Bash, Edit, Write]外部情報の取得のみ

「最小権限の原則」をSub-agent単位で機械的に効かせられるのが、Skillとは異なる強みです。Skillは呼び出し側のコンテキスト権限で動きますが、Sub-agentは自前の権限境界を持ちます。

モデル選択の経済性

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

用途推奨モデル理由
重い思考・複雑な独自視点Opus推論深度が必要。コスト高でも品質を取る
標準的な執筆 / 調査Sonnet速度と品質のバランス
単純な抽出 / 採点判定Haiku高速 + 安価。明確な判定基準があればHaikuで十分
WebFetch + JSON抽出Haiku構造的タスクは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倍速くなることが多く、独立調査タスクには特に効きます。

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

向くケース向かないケース
3〜5個の独立した調査(KW調査 + 競合 + 一次ソース 等)結果が前段の出力に依存する場合(draft → fact-check → quality-judge)
複数ファイル / 複数ドメインへのWebFetch同じファイルへの書き込みが衝突する場合
matrix評価(複数モデル比較 / 複数アプローチ比較)ツールが矛盾する状態を読む(片方が書いて、もう片方が読む)

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

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

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

状況推奨レイヤー理由
メインのコンテキストを汚さず重い処理を任せたいSub-agent独立コンテキストの強み
ツール権限を厳しく絞りたいSub-agentツール制限の機械的強制
軽量モデルで安く高速に走らせたいSub-agentmodel指定でルーティング
並列で複数を独立に走らせたいSub-agent独立コンテキストで安全に並列
メインの会話文脈で完結する手順書Skillコンテキストを共有したい場合はSkillが向く
プロジェクト全体に常駐するルールCLAUDE.md常駐はCLAUDE.md、呼び出し型はSkill / Sub-agent
外部システム / 状態保持が必要MCPAPI呼び出しはMCPの責務

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

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を呼べません。orchestratorパターンを組むなら明示的に tools: [Agent, ...] と書き、許可する subagent_type リストもセットで定義します。

つまずき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」から始め、慣れたらレビュー / 採点 / オーケストレーションへ展開する形が安定して育てやすいでしょう。

この記事を共有:XLinkedIn

関連する記事

Claude Code をもっと見る →