Claude Codeのサブエージェントを使いこなすには、APIの使い方を覚えるだけでは不十分です。失敗パターンを理解し、それを避ける委譲設計を作ることが本質です。本記事では、実際のプロダクトコードベースで機能しているパターンと、理論上は正しいが実運用で崩れるパターンを整理します。
サブエージェントの基本を学ぶ場合はサブエージェントガイドを先に読んでください。本記事は基礎知識があることを前提に最適化に焦点を当てます。
実際のAGENTS.mdサンプルはギャラリーで確認できます。
最も多い失敗パターン：仕様の曖昧さ
AGENTS.mdのエントリが曖昧すぎることが、サブエージェント運用で最もよく見られる失敗の原因です。
## research-agent
トピックをリサーチして結果を返す。これでは「結果」の形式も、調査の深さも、行き詰まったときの対処も何も定義されていません。結果は毎回バラバラになり、受け取ったオーケストレーターが解釈のためにトークンを消費することになります。
改善版はこうなります：
## research-agent
特定の技術トピックをリサーチし、構造化されたレポートを返す。
### 入力
以下のJSONオブジェクトを受け取る：
- `topic`: 調査対象（文字列）
- `depth`: "overview" | "deep-dive"
- `sources`: 優先URLの配列（空の場合はオープンリサーチ）
### 出力フォーマット
以下のセクションで構成されるmarkdownレポートを返す：
1. サマリー（3〜5文）
2. 主要な知見（箇条書き、最大10項目）
3. 未確認事項・ギャップ（確認できなかった点）
4. 参照ソース（URLリスト）
### 制約
- 合計1,500語を超えない
- `depth`が"overview"の場合、ツール呼び出しは5回まで
- ソースにアクセスできない場合は失敗せず「未確認事項」に記載するこのように定義することで、毎回一貫したパース可能な出力が得られます。
タスク分解：何をどう分けるか
効果的な分解には以下の特徴があります。
明確な境界。 各サブエージェントが担当する範囲が明確であること。責任が重なると作業の重複や結果の上書きが発生します。
独立した入力。 他のサブタスクの完了を待たずに実行できること（依存がある場合はその順序を明示します）。並列処理はタスクが本当に独立している場合にのみ意味があります。
スコープの制限。 スコープを制限しなければ、エージェントは開放的な調査を始めます。ツール呼び出し数の上限、出力の最大長、調査範囲の明示的な制限が必要です。
具体的な完了条件。 エージェントが「完了」を判断できる基準を設けます。「機能を実装する」では不十分です。「npm testがエラーなしで通過する状態で機能を実装する」が正しい形です。
分解のテンプレート
大きなタスクに取り組む前に、このフォーマットで整理します：
タスク: [何を達成するか]
サブタスク:
1. [サブタスクA — 独立]
2. [サブタスクB — 独立]
3. [サブタスクC — AとBの出力に依存]
各サブタスクについて：
- 入力: [何を渡すか]
- 出力: [何が返ってくるか]
- 制約: [スコープの上限]
- 完了条件: [検証可能な条件]このプロセスにより、実行中に発覚する隠れた依存関係を事前に特定できます。
コンテキストの受け渡し：適切な情報量
サブエージェントは与えられた情報しか知りません。ただし、情報の与えすぎは情報不足と同様に有害です。渡すトークンは、エージェントが実際の作業に使えないトークンです。
生データではなく要約を渡す
コードベースを理解させる場合、コード全体をダンプするのではなく、構造化された要約を渡します：
## コードベースコンテキスト
- 言語: TypeScript, Node.js 20
- アーキテクチャ: Express REST API、PrismaでPostgreSQL接続
- このタスクに関連するファイル:
- src/api/users.ts（ユーザーCRUDエンドポイント）
- src/lib/db.ts（DBクライアントとクエリヘルパー）
- prisma/schema.prisma（データモデル）
- 規約: 名前付きエクスポート使用、DBカラムはsnake_case、コードはcamelCase
- テストコマンド: npm testこれで正しく動作するための情報は十分です。
ハンドオフを構造化する
順次実行ワークフローでエージェント間の結果を受け渡す場合：
## [前エージェント]からのハンドオフ
ステータス: 完了
出力:
- src/api/payments.tsに3つの新しいAPIエンドポイントを作成
- src/schemas/payment.tsにZodスキーマを追加
- テストはsrc/api/__tests__/payments.test.ts
発生した問題:
- Stripeウェブフックエンドポイントに認証ミドルウェアが未実装
あなたのタスク:
- 不足している認証ミドルウェアを実装（既存パターンはsrc/middleware/参照）
- ウェブフックエンドポイントに接続
- 全ペイメントテストが通過することを確認これにより、2番目のエージェントが前のエージェントが処理済みの内容を再度読む必要がなくなります。
並列 vs 順次：使い分けの基準
並列サブエージェントを使うべき場合：
- タスクが本当に独立している（共有状態なし、順序依存なし）
- 各タスクがオーバーヘッドを正当化できる大きさを持つ
- コンテキスト予算が逼迫していて作業を分離したい
順次サブエージェントを使うべき場合：
- タスクAの出力がタスクBの入力になる
- タスクが状態を共有している（同じファイル、同じDB）
- 成功を確認してから次に進む必要がある（「テストが通ったら続行」等）
アグリゲーターパターン
最も信頼性の高いマルチエージェントパターンのひとつです：
オーケストレーター
→ N個の並列サブエージェントを起動（各エージェントが1スライスを担当）
→ 全エージェントの完了を待機
→ 1個のアグリゲーターサブエージェントを起動（N個の出力を全て受け取る）
→ アグリゲーターの結果を返すアグリゲーターによりメインコンテキストがクリーンに保たれます。N個の出力をオーケストレーターが直接処理する必要がなくなります。
AGENTS.md の構造的ベストプラクティス
一貫したヘッダー構造を使う
全エントリを同じ構造にすることで、モデルが確実にエントリを解析できます：
## [エージェント名]
[1行の目的説明]
### 使用する場面
[このエージェントを呼び出す条件]
### 入力
[何を受け取るか]
### 出力
[何を返すか、フォーマット仕様を含む]
### 制約
[動作・スコープ・出力サイズの制限]ファイルをコンテキストで分割する
大規模プロジェクトでは複数のAGENTS.mdファイルを使います：
~/.claude/AGENTS.md → どこでも使えるグローバルエージェント
./AGENTS.md → プロジェクトレベルのエージェント
./packages/api/AGENTS.md → API専用エージェント
./packages/frontend/AGENTS.md → フロントエンド専用エージェントカレントディレクトリに近いエントリが優先されるため、特定パッケージでグローバル設定を上書きできます。
エントリを短く保つ
AGENTS.mdファイル全体がセッションのたびにコンテキストに読み込まれます。100行のエントリは約750トークンのオーバーヘッドになります。各エントリは40行以内、AGENTS.md全体は300行以内を目安にしてください。長い仕様が必要な場合は外部ファイルへの参照を使います：
## complex-migration-agent
データベーススキーママイグレーションを処理する。完全な仕様は`docs/agents/migration-agent.md`参照。エージェント自身が参照ファイルを読むことができるため、全てをインライン化する必要はありません。
ツール権限のスコーピング
サブエージェントは設定を上書きしない限り、グローバル設定のツール権限を継承します。権限を絞ることで：
- エージェントが誤った判断をした場合の影響範囲を限定できる
- 開放的な動作を制限できる（ウェブブラウジングできなければ作業に集中する）
- 動作の予測可能性が上がる
コードレビューエージェントであれば、ファイルの読み取りアクセスは必要ですが、書き込みやシェル実行は不要です。
## code-review-agent
プルリクエストのdiffをレビューして構造化されたフィードバックを返す。
### 権限
- 許可: read_file, list_files
- 拒否: write_file, execute_bash, browser_navigateエラーハンドリング
サブエージェントは失敗します。重要なのはオーケストレーション層がその失敗にどう対処するかです。
失敗シグナルを定義する
### 失敗時の動作
タスクを完了できない場合は以下を返す：
{
"status": "failed",
"reason": "簡潔な説明",
"completed_portion": "失敗前に完了した部分",
"retry_possible": true/false
}
不確かな状態で推測や部分的な出力を返さないこと。段階的な劣化設計
サブエージェントの失敗がパイプライン全体を崩壊させないように設計します。オプショナルな補完ステップが失敗した場合はスキップして継続。必須ステップが失敗した場合は、不正なデータで処理を続行せず、明確なエラーで停止します。
実際のAGENTS.mdパターンはさらにギャラリーで確認できます。コンテキスト管理の戦略についてはCLAUDE.mdトークン最適化ガイドも参照してください。