Claude Codeのサブエージェントは、メインの会話とは別のコンテキストで特定タスクを実行する仕組みです。本記事では、サブエージェントを使いこなすための実践パターンを紹介します。読み終える頃には、.claude/agents/の設計方針、役割分担のコツ、並列実行による高速化、そしてアンチパターンの回避方法が身につきます。

サブエージェントとは何か

サブエージェントは、Claude Codeのメインセッションから独立したコンテキストウィンドウを持つ専門エージェントです。Agentツール経由で起動され、独自のシステムプロンプト・利用可能ツール・モデル設定を持ちます。

最大のメリットはコンテキスト分離です。たとえば大規模リポジトリ全体を調査させる場合、メインセッションに調査結果のノイズを持ち込まず、サブエージェントに「結論だけ200字で報告」と指示することで、メインの作業領域を清潔に保てます。

定義は~/.claude/agents/（グローバル）または.claude/agents/（プロジェクト）にMarkdownファイルとして配置します。

---
name: reviewer
description: 差分のコードレビューを行う読み取り専用エージェント
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたは厳格なシニアエンジニアです。
以下の観点で差分をレビューしてください:
- 型安全性
- N+1クエリ
- エラーハンドリング漏れ
- 命名の一貫性

出力は「指摘事項のリスト」のみ。修正コードは書かないでください。

パターン1: 読み取り専用レビュアー

もっとも実用的なパターンが書き込み権限を持たないレビュアーです。toolsからEdit/Writeを除外することで、レビュー中に勝手にコードを書き換える事故を防げます。

---
name: security-auditor
description: SQLインジェクション・XSS・認証バイパスを検出
tools: Read, Grep, Glob
model: opus
---

OWASP Top 10の観点で差分を監査してください。
発見した脆弱性は CVSS スコア（推定）と共に報告してください。
修正提案は「方針のみ」記述し、コードは書かないでください。

呼び出し側のメインエージェントは、レビュー結果を受け取ってから自分で修正を実装します。これにより「レビュー」と「修正」の責任が明確に分離され、修正漏れや意図しない変更を抑えられます。

パターン2: 調査特化エージェント（Explore型）

大規模コードベースで「この機能はどこで実装されているか」を調べるとき、メインセッションでGrepを連打するとコンテキストが汚染されます。調査専用エージェントに丸投げするのが推奨されています。

---
name: explorer
description: コードベースを横断調査し、関連箇所を簡潔に報告
tools: Read, Grep, Glob, Bash
model: haiku
---

あなたは調査エージェントです。
- 関連ファイルとline番号をリストで返す
- 各箇所に1行の要約をつける
- 400字以内に収める
- ファイル全文を貼り付けない

ポイントはモデルにHaikuを指定することです。単純な検索タスクに高価なOpusを使う必要はなく、Haikuなら高速・低コストで済みます。重要な判断を伴う場合のみOpusに切り替えるのが一般的です。

パターン3: 並列実行で開発速度を倍化

Claude Codeは複数のサブエージェントを同一メッセージ内で並列起動できます。独立したタスクをまとめて投げると、待ち時間が劇的に短縮されます。

メインエージェント側のプロンプト例:

以下を並列で実行してください:
1. exploreエージェント: 認証フローの実装箇所を調査
2. reviewerエージェント: PR #123の差分をレビュー  
3. testerエージェント: lib/auth/ のテストを実行

Claude Codeはこれを単一のターンで3つのAgentツール呼び出しに展開し、並列実行します。シーケンシャルに実行すると合計5分かかる作業が、並列なら2分で終わるケースも珍しくありません。

ただし依存関係があるタスクは並列化できません。「調査結果を踏まえて修正」のような順序依存のあるフローは、Aの結果を受けてからBを起動する必要があります。

パターン4: テスト実行とフィードバックループ

テスト実行を専用エージェントに任せると、メインセッションのコンテキストを温存できます。

---
name: tester
description: テストを実行し、失敗したテストのみ報告
tools: Bash, Read
model: sonnet
---

テストを実行し、以下のフォーマットで報告してください:

## 失敗したテスト
- ファイル:行番号
- エラーメッセージの要点（1行）
- 推定原因

成功したテストの一覧は不要です。
全件成功した場合は「全テストパス」とだけ報告。

メインエージェントは「失敗箇所のリスト」だけを受け取り、修正に集中できます。テストランナーの長大な出力でコンテキストが圧迫される問題を回避できます。

アンチパターンと注意点

1. サブエージェントの乱用 単純な1ファイル読み取りや1回のGrepでサブエージェントを起動するのは過剰です。サブエージェント起動には初期化コストがかかるため、3クエリ以上の調査や、メインコンテキストを汚したくない場合に限定するのが推奨されています。

2. プロンプトの曖昧さ サブエージェントは会話履歴を継承しません。「さっきの件」「あのファイル」は通じないため、プロンプトにファイルパス・行番号・前提条件をすべて明記する必要があります。

3. 結果の長さを指定しない 「report in under 200 words」のような長さ制約を入れないと、サブエージェントは長文を返しがちで、コンテキスト節約の意味が薄れます。

4. 書き込み権限を不用意に与える レビュアー・調査エージェントにはEdit/Writeを渡さないのが原則です。意図しないファイル変更を防げます。

まとめ

サブエージェントは「コンテキスト分離」と「並列化」という2つの強力な武器を提供します。.claude/agents/にreviewer・explorer・testerといった役割別の定義を置き、適切なモデル・ツール・プロンプトを与えることで、Claude Codeの作業効率は劇的に向上します。重要なのは、責任を細かく分割し、各エージェントに「結果は簡潔に」と指示すること。このパターンを習慣化すれば、大規模リポジトリでも快適に開発を続けられます。