Claude Code を使い込むと、1つのセッションにすべてを任せるより「役割ごとに分けたサブエージェント」へ仕事を振り分けたほうが、速く・正確に・コンテキスト切れせずに進むことに気づきます。本記事では、Claude Code のサブエージェントを実際に運用した手順を、設定ファイルの中身・呼び出し方・並列実行・つまずいた罠まで、コピペで再現できる形で解説します。
サブエージェントとは？通常のClaude Codeと何が違うのか
サブエージェントとは、特定の役割（例：コードレビュー、テスト実行、調査）に特化させた独立コンテキストのClaudeです。メインのセッションから仕事を切り出して渡すと、サブエージェントは自分専用の会話履歴・専用のツール権限・専用のシステムプロンプトで作業し、結論だけをメインに返します。
これが効くのは次の3点です。
- コンテキスト汚染を防ぐ：大量のファイルを読む調査タスクを切り出せば、メインの会話に検索ノイズが流れ込まない。返ってくるのは要約だけ。
- 役割ごとに最適化できる：レビュー役は厳しめのプロンプト、生成役は別プロンプト、とキャラを分けられる。
- 並列で同時に走らせられる：独立しているので、複数のサブエージェントを一度に起動して待ち時間を短縮できる。
サブエージェントの作り方：.claude/agents/ に1ファイル置くだけ
サブエージェントは .claude/agents/ ディレクトリ（プロジェクト単位）または ~/.claude/agents/（全プロジェクト共通）に Markdown ファイルを1つ置くだけで定義できます。先頭の YAML フロントマターで設定し、本文がそのエージェントのシステムプロンプトになります。
---
name: code-reviewer
description: 変更差分をレビューしてバグと改善点を指摘する専門エージェント
model: sonnet
tools: Read, Grep, Bash
---
あなたはシニアのコードレビュアーです。与えられた差分に対して：
1. 明確なバグ（null参照・境界条件・例外未処理）を最優先で指摘
2. 命名・重複・過剰な複雑さなど可読性の問題を指摘
3. 確信度の低い指摘は「要確認」と明示する
指摘は file:line 形式で、修正案を添えて返してください。各フィールドの意味は次の通りです。
| フィールド | 役割 | 例 |
|---|---|---|
name | エージェントの識別名（呼び出しに使う） | code-reviewer |
description | 「いつ使うか」。Claudeはこれを見て自動委譲を判断する | 差分レビュー専門 |
model | 使うモデル。軽い作業はhaiku、難所はopusと使い分け | sonnet / opus / haiku |
tools | 許可するツール。絞るほど安全で速い | Read, Grep, Bash |
tools を省略するとメインと同じ全ツールを継承します。レビュー役に Write を与えない、のように最小権限で絞るのがコツです。
呼び出し方：自動委譲と明示呼び出しの2通り
定義したサブエージェントは2つの方法で起動します。
① 自動委譲：タスク内容が description に合致すると、Claude Code が自動でそのサブエージェントに振ります。明示しなくても「差分をレビューして」と頼めば code-reviewer が呼ばれます。
② 明示呼び出し：確実に使わせたいときは名前を指定します。
use the code-reviewer subagent to review my staged changes登録済みのサブエージェント一覧は /agents コマンドで確認・編集できます。
実践：複数サブエージェントの並列実行でレビュー時間を短縮
サブエージェントの真価は並列実行にあります。たとえば「バグ」「セキュリティ」「パフォーマンス」の3観点でレビューしたいとき、3つのサブエージェントを同時に起動すれば、直列で3回回すより待ち時間が大幅に減ります。1つのメッセージで複数のエージェントを呼べば、Claude Code はそれらを並行して走らせます。
実運用での体感差は次の通りでした（中規模の差分・3観点レビューの例）。
| 方式 | 進め方 | 体感の待ち時間 | コンテキスト |
|---|---|---|---|
| 直列（1セッション） | 1つのClaudeに3観点を順番に | 長い（観点ごとに積み上がる） | 後半ほどノイズで劣化 |
| 並列サブエージェント | 3エージェントを同時起動→結論だけ集約 | 最も遅い1本ぶんで済む | 各自クリーンなまま |
ポイントは「メインは指揮に専念し、重い読み込みは各サブエージェントに閉じ込める」こと。返ってくるのが要約だけなので、メインの会話は最後まで見通しよく保てます。
運用でつまずいた3つの罠と解決策
1. 全部 opus にして遅い・高コストになった
最初はすべて高性能モデルにしていましたが、単純な検索や定型整形まで重いモデルを使うと遅く高くつきます。調査・整形は haiku、レビューは sonnet、設計判断は opus と model をタスク難度で割り当てたら、速度とコストが両立しました。
2. tools を絞らず、レビュー役がファイルを書き換えた
レビュー専用のつもりが tools 未指定で Write を継承しており、勝手に修正してしまうことがありました。役割に必要なツールだけを明示（レビューは Read, Grep のみ）すれば、想定外の副作用を防げます。
3. サブエージェントに文脈を渡し忘れて的外れな結論が返った
サブエージェントはメインの会話を自動では共有しません。渡すときに「対象ファイル・前提・期待する出力形式」を明記する必要があります。指示テンプレートを CLAUDE.md に書いておくと、毎回ブレずに渡せます。
Codex CLI・Cursorとの違い
同じ「AIコーディング」でも設計思想が異なります。用途で選ぶのが現実的です。
| ツール | 強み | サブエージェント的な分業 |
|---|---|---|
| Claude Code | ターミナル常駐・ファイル定義のサブエージェント・並列実行・CLAUDE.md/MCP拡張 | 得意（役割をファイルで量産できる） |
| Codex CLI | OpenAIモデルでのCLI補完・コード生成 | 分業より単体補完寄り |
| Cursor | エディタ統合のUX・補完とチャットの一体感 | IDE内作業に最適 |
「役割を分けて並列で回し、結論を集約する」運用を重視するなら、ファイル定義でエージェントを増やせる Claude Code が扱いやすい、というのが実運用の結論です。
まとめ
Claude Code のサブエージェントは、.claude/agents/ に1ファイル置くだけで始められ、独立コンテキスト・最小権限・並列実行の3点で効きます。まずは「レビュー役」を1つ作り、model と tools をタスクに合わせて絞るところから試してみてください。役割が増えるほど、メインのClaudeは”指揮官”として身軽になり、開発全体のスピードと精度が上がります。
