Claude Codeとサブエージェントの概要
Claude Codeは「Agentツール」を通じてサブエージェント（子エージェント）を起動できます。親エージェント（Claude Code本体）が大きなタスクを分割し、サブエージェントに個別のタスクを割り当てて並列実行することで、処理全体を高速化したり役割を分離したりできます。
たとえば「コードレビューをして、テストを書いて、ドキュメントを更新して」という指示を受けたとき、親エージェントはこれを3つのサブタスクに分割し、それぞれをサブエージェントに委任して並列実行できます。
サブエージェントの起動方法
Claude CodeはAgentツールを呼び出すことでサブエージェントを起動します。このとき親エージェントは以下を指定します。
- タスクの説明（promptパラメータ）
- 使用するモデル（subagent_typeパラメータ）
- バックグラウンド実行か否か（run_in_backgroundパラメータ）
サブエージェントは起動すると独立した環境で動き始めます。親エージェントのメモリやコンテキストは引き継ぎません。そのため、サブエージェントへの指示は「それだけ読んで分かる」自己完結した内容にする必要があります。
これは重要なポイントです。「さっきの話をベースに修正して」という指示ではサブエージェントに文脈が伝わりません。「/path/to/auth.ts の認証ロジックを読んで、JWTトークンの有効期限チェックを追加してください。現在の実装は〇〇で、期待される動作は〇〇です」のように具体的に書く必要があります。
並列実行とシリアル実行の使い分け
並列実行が有効な場面
独立したサブタスクが複数ある場合に適しています。
- 複数ファイルの独立したリファクタリング
- 異なるモジュールのテスト作成
- 複数のAPIエンドポイントの調査
これらは互いに依存しないため、並列で実行してもコンフリクトが起きません。
シリアル実行が必要な場面
タスクに依存関係がある場合は直列実行が必要です。
- データベーススキーマを変更してから、それを使うコードを修正する
- テストを先に書いてから、テストが通るコードを実装する
- ビルドして問題がないか確認してからデプロイする
並列で実行してしまうと、先行タスクの結果を後続タスクが使えずエラーになる場合があります。
ファイル競合の問題
並列実行の最大のリスクが、複数のサブエージェントが同じファイルを編集しようとする競合です。
たとえば「サブエージェントA：utils.ts を最適化」「サブエージェントB：utils.ts に新しい関数を追加」を並列実行すると、どちらかの変更が失われる可能性があります。
回避策は明確な責任分割です。
- ファイル単位で担当を分ける
- 1つのサブエージェントには1つのファイル（または明確に区切られた範囲）だけを担当させる
- サブエージェントが触るファイルが重ならないようタスク分割を設計する
結果の統合と検証
サブエージェントが完了すると、結果が親エージェントに返されます。親エージェントはこれらの結果をまとめて整合性を確認します。
サブエージェントが「成功した」と報告しても、実際には想定外の動作をしている可能性があります。信頼するが検証する（Trust but Verify）の姿勢で、親エージェントが結果を再確認する設計が重要です。
Claude Codeの設計ではサブエージェントの出力を要約として受け取り、重要な変更については親エージェントが実際のファイルを確認するプロセスが推奨されています。
コンテキストとコストの管理
サブエージェントはそれぞれ独立したコンテキストを持ちます。親エージェントから大量のコンテキストを渡すとトークンコストが増加します。必要最小限の情報だけを渡すことがコスト最適化につながります。
具体的には、ファイルの全文ではなく「〇〇ファイルの認証関連の関数に限定して作業してください」と範囲を絞る指示が効果的です。サブエージェントが自分で必要なファイルを読むようにすれば、親エージェントが事前に大量のコンテキストを渡す必要がなくなります。
サブエージェントの失敗処理
サブエージェントが途中でエラーになったり、期待通りの結果を返さなかった場合の処理も設計が必要です。
親エージェントは各サブエージェントの完了ステータスと結果を確認し、失敗したサブタスクについては再試行するか、別のアプローチを取るかを判断します。
タイムアウト設定も重要です。無限に実行されるサブエージェントを放置するとコストが際限なく増加します。
まとめ
Claude Codeのサブエージェント機能は、独立したタスクを並列実行することで処理を効率化する強力な仕組みです。成功の鍵はタスク分割の設計にあります。依存関係のないタスクを並列実行し、ファイル競合が起きない責任分割を行い、自己完結した指示を渡すことで、サブエージェントが適切に動作します。結果の検証と失敗時の処理を親エージェント側で設計することも忘れずに。
