Subagents（サブエージェント）入門

Claude Code を使い込んでいくと、調査やコード生成のたびにメインの会話（コンテキスト）がどんどん長く重くなっていきます。そこで役立つのが Subagent（サブエージェント） です。サブエージェントは、メインの Claude が特定のタスクを「別の Claude」に丸投げするための仕組みで、文脈の節約・並列処理・専門特化という大きなメリットをもたらします。この記事では、サブエージェントの考え方から定義ファイルの書き方、組み込みエージェント、並列化の注意点までをまとめます。

サブエージェントとは「別の文脈を持つ部下」

サブエージェントとは、あなたと対話しているメインの Claude が、特定のタスクを別の Claude インスタンスに任せる仕組みです。一番のポイントは、サブエージェントが独立した文脈（コンテキスト）で作業し、メインには結論だけを返すという点にあります。

イメージとしては「別室で作業する部下」です。部下は自分の机（独立した文脈）で大量の資料を広げて調べ、終わったら結論を一枚にまとめて上司（メイン Claude）に渡します。上司の机の上には、部下が広げた資料の山は一切残りません。

サブエージェントはメインの文脈を引き継ぎません。必要な情報は呼び出すときに明示的に渡す必要があります。途中経過も見えないため、内部のやり取りはデバッグしづらい点に注意してください。

なぜサブエージェントが必要か — 3大メリット

サブエージェントを使う理由は、大きく次の3つに整理できます。

1. 文脈の節約

大量の調査や探索をサブエージェント側で完結させ、メインには結論だけを返します。これにより、メインの文脈が中間的な情報で汚れず、長い作業でも会話が軽いまま保てます。たとえば「このコードベース全体からエラーハンドリングの実装箇所を洗い出す」といった膨大な読み取りも、結果の要約だけがメインに戻ってきます。

2. 並列処理

複数のサブエージェントを同時に走らせることができます。調査・コード生成・テストなどを並列化することで、全体の作業時間を短縮できます。

3. 専門特化

サブエージェントごとに専用のシステムプロンプトとツール制限を持たせられます。「コードレビュー専門」「テスト作成専門」のように役割を絞ることで、振る舞いが安定し、余計な操作を防げます。

サブエージェントの定義ファイル

サブエージェントは Markdown ファイルとして定義します。配置先は次の2通りです。

• プロジェクト単位：.claude/agents/ ディレクトリ
• ユーザー単位：~/.claude/agents/ ディレクトリ

ファイルの先頭にメタ情報（フロントマター）を --- で囲んで書き、その下にシステムプロンプト（エージェントへの指示）を本文として書きます。

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: コードレビュー専門。PRやコミット前の差分をレビューする。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたは経験豊富なコードレビュアーです。
以下の観点でコードをレビューしてください：

- バグやエッジケースの見落とし
- セキュリティ上の懸念
- 可読性・保守性
- パフォーマンス

指摘は重要度順に、具体的な修正案とともに提示してください。

フロントマターの各フィールド

• name（必須）… サブエージェントの識別名。英小文字とハイフンで付けます。
• description（必須）… いつこのエージェントを使うか。メインの Claude はこの説明文を見て自動で呼び出すため、用途を具体的に書くことが重要です。
• tools（任意）… 使用可能なツールを制限します。省略すると全ツールを継承します。
• model（任意）… 使うモデル（sonnet / opus / haiku）。省略するとデフォルトのモデルが使われます。

--- より下の本文が、そのエージェントのシステムプロンプトになります。役割・観点・出力形式などを明確に書くほど、専門特化の効果が高まります。

組み込みエージェント

Claude Code には、最初からいくつかのサブエージェントが用意されています。自分で定義しなくても、これらをそのまま使えます。とくに ツール制限（何ができ、何ができないか）を理解しておくと、安全で意図どおりの使い分けができます。

claude / general-purpose（汎用）

• claude … 汎用エージェント。メインと同じ全能力を持ち、ツール制限なし。
• general-purpose … 複雑な調査や多段タスク向けの汎用エージェント。全ツールを使えます。

Explore / Plan（読み取り専用）

• Explore … コードベースの探索・調査専用。読み取りのみで、ファイルへの書き込みはできません。
• Plan … 計画立案専用。コードを書かずに方針を立てます。こちらも読み取り専用（書き込み不可）。

この2つが書き込み不可なのは安全のためです。調査や計画の段階で誤ってファイルを変更してしまう事故を防ぎ、「まず調べる・まず考える」を安心して任せられます。

claude-code-guide / statusline-setup（限定的）

• claude-code-guide … Claude Code の使い方を案内する。ツールは限定的。
• statusline-setup … ステータスライン設定の補助。ツールは限定的。

最小権限という考え方

組み込みエージェントのツール制限は、そのタスクに必要な権限だけを与えるという「最小権限」の考え方に沿っています。自分でエージェントを定義するときも、tools を絞って必要なものだけ許可するのが安全です。

使い方：自動呼び出しと明示呼び出し

サブエージェントの呼び出し方は2通りあります。

• 自動呼び出し：メインの Claude がタスク内容と各エージェントの description を照らし合わせ、適切なものを自動で選んで呼びます。だからこそ説明文を具体的に書くことが大切です。
• 明示呼び出し：「code-reviewer エージェントを使ってレビューして」のように、ユーザーが名指しで指定します。

並列化と worktree 隔離

複数のサブエージェントに書き込みを伴う作業を並列でさせる場合、注意が必要です。同じファイルを同時に編集すると衝突してしまうからです。

これを避けるために使うのが git worktree です。worktree を使うと、1つのリポジトリから複数の作業ディレクトリを切り出せます。各サブエージェントを別々のブランチ・別々の作業ディレクトリで作業させ、あとでまとめて（マージして）統合します。

worktree 隔離が必要なのは「書き込みを並列でする」場合です。読み取り専用の調査（Explore など）を並列で走らせるだけなら、隔離は不要です。

司令塔パターン

サブエージェントを活かす代表的な構成が司令塔（オーケストレーター）パターンです。メインの Claude が司令塔となり、複数のサブエージェントに仕事を割り振ります。

ここで重要なのは、各サブエージェントの最終メッセージだけが司令塔に返されるという点です。途中経過は捨てられてしまうため、サブエージェント側は結論を最後にきちんとまとめることが欠かせません。最後の一通に必要な情報がすべて入っていないと、せっかくの作業結果が司令塔に届きません。

まとめ

• サブエージェントは「別文脈で働く部下」。独立した文脈で作業し、結論だけをメインに返す。
• メリットは文脈の節約・並列処理・専門特化の3つ。
• 定義は .claude/agents/（または ~/.claude/agents/）の Markdown。name と description は必須、tools と model は任意。
• 組み込みでは Explore と Plan が読み取り専用。最小権限で安全に使う。
• 書き込みを並列化するときは worktree 隔離で衝突を防ぐ。読み取りだけなら不要。
• 司令塔パターンでは最終メッセージだけが返る。結論を最後にまとめること。