Claude Code サブエージェント｜並列処理で開発を高速化する方法
Claude Code を使い込んでいくと、「1つのタスクを処理している間に、別の調査も同時に進めてほしい」「大規模なリファクタリングを複数ファイル同時に進めたい」と感じる場面が増えてきます。
そうした要望に応えるのが、Claude Code のサブエージェント機能です。メインの Claude Code セッションが子プロセスとして別の Claude Code を起動し、調査や分析を並列で実行させることで、開発の速度と精度を大幅に向上させます。
本記事では、サブエージェントの仕組みから、並列処理の具体例、コードリサーチの委譲パターン、大規模リファクタリングでの活用、制限事項、そして効果的な使い方のコツまでを体系的に解説します。
サブエージェントとは何か
サブエージェントとは、Claude Code のメインエージェントが特定のタスクを別の Claude Code インスタンスに委譲する仕組みです。内部的には Task ツールと呼ばれる機能によって実現されています。
Task ツールの基本
Claude Code は対話中にさまざまな「ツール」を使い分けています。ファイルを読む Read ツール、ファイルを編集する Edit ツール、コマンドを実行する Bash ツールなどがその例です。Task ツールはこれらと同列に存在する機能で、新しい Claude Code エージェントを子プロセスとして起動し、独立したタスクを実行させることができます。
通常の対話では、Claude Code は1つのプロンプトに対して順番に処理を進めます。しかし Task ツールを使うと、メインエージェントが「この調査はサブエージェントに任せよう」と判断し、子プロセスを立ち上げて並列に作業を進められるようになります。
メインエージェント
├── サブエージェント A: 「認証モジュールの実装パターンを調査」
├── サブエージェント B: 「テストファイルの構造を分析」
└── サブエージェント C: 「依存関係の影響範囲を特定」
通常のツール呼び出しとの違い
Read ツールや Bash ツールは「1つの操作を実行して結果を返す」単発のツールです。一方、Task ツールで起動されたサブエージェントは、自分自身がさらに Read・Edit・Bash・Grep などのツールを使いながら、複数ステップにわたる作業を自律的に進められます。
つまりサブエージェントは、単なるツール呼び出しではなくミニチュア版の Claude Code セッションです。メインエージェントから与えられた指示に基づき、必要なファイルを自分で探し、読み、分析し、結果をまとめてメインエージェントに返却します。
サブエージェントの仕組み
サブエージェントがどのように動作するかを、もう少し詳しく見ていきましょう。
メインエージェントと子プロセスの関係
メインエージェントは、ユーザーとの対話を担当する「親」プロセスです。ユーザーの指示を受け取り、必要に応じてサブエージェントを起動します。
サブエージェントは以下の特徴を持ちます。
- 独立したコンテキスト: メインエージェントの会話履歴全体は引き継がず、Task ツールで渡された指示のみをコンテキストとして動作する
- 読み取り専用のツール制限: サブエージェントはファイルの読み取りや検索（Read、Grep、Glob など）は実行できるが、ファイルの編集や書き込みはできない
- 結果の返却: 作業が完了すると、分析結果や調査結果をテキストとしてメインエージェントに返す
- 並列実行: 複数のサブエージェントが同時に起動され、並列に作業を進めることができる
起動から結果返却までの流れ
サブエージェントの典型的なライフサイクルは以下の通りです。
- メインエージェントが Task ツールを呼び出す: 「このコードベースで認証がどのように実装されているか調査して」といった指示を渡す
- サブエージェントが起動される: 独立した Claude Code インスタンスとして動作を開始する
- 自律的に調査を進める: Grep でキーワード検索し、Glob でファイルを探し、Read で内容を確認する。必要に応じて複数のステップを踏む
- 結果をまとめて返却する: 調査結果を構造化されたテキストとしてメインエージェントに返す
- メインエージェントが結果を統合する: 複数のサブエージェントの結果を統合し、ユーザーへの応答や次のアクションに活用する
この一連の流れは、ユーザーから見ると Claude Code が内部的に処理しているため、特別な操作は必要ありません。
コンテキストの分離
サブエージェントの重要な設計上の特徴として、コンテキストの分離があります。メインエージェントの会話履歴が長くなっても、サブエージェントは Task ツールで渡された指示だけを見て動作します。
これにより以下のメリットが得られます。
- トークン効率が良い: サブエージェントは必要最小限のコンテキストで動作するため、トークン消費を抑えられる
- メインのコンテキストウィンドウを圧迫しない: 大量のファイル調査の結果がメインエージェントのコンテキストに直接蓄積されない
- タスクに集中できる: 余計な文脈がないため、与えられたタスクに対して的確に動作する
並列処理の具体例
サブエージェントの最大の強みは並列処理です。実際の開発でどのように活用できるかを具体例で見ていきましょう。
複数ファイルの同時調査
大きなコードベースで特定の機能がどこに実装されているかを調べたい場合、サブエージェントを使えば複数の観点から同時に調査できます。
たとえば「ユーザー認証の流れを把握したい」という指示に対して、Claude Code は以下のようにサブエージェントを並列起動することがあります。
メインエージェント: 「ユーザー認証の全体フローを把握したい」
│
├── サブエージェント 1: 認証ミドルウェアの実装を調査
│ → auth middleware、JWT 検証、セッション管理のコードを特定
│
├── サブエージェント 2: ログイン・サインアップの API エンドポイントを調査
│ → ルーティング定義、ハンドラ実装、バリデーションロジックを特定
│
└── サブエージェント 3: 認証関連のテストコードを調査
→ テストケース、モック設定、カバレッジ状況を把握
メインエージェントは3つのサブエージェントの結果を統合して、認証フロー全体の包括的な説明をユーザーに提供します。1つずつ順番に調べるよりも、大幅に速く全体像を把握できます。
依存関係の影響範囲調査
あるモジュールを変更したとき、その変更がどこに影響するかを調べるのは重要ですが手間のかかる作業です。サブエージェントを使えば、複数の観点から同時に影響範囲を調査できます。
「UserService クラスのインターフェースを変更したい。影響範囲を調べて」
│
├── サブエージェント 1: UserService を直接インポートしているファイルを列挙
├── サブエージェント 2: UserService のメソッドを呼び出しているコードを検索
├── サブエージェント 3: UserService に関連するテストファイルを特定
└── サブエージェント 4: UserService を利用している API エンドポイントを調査
テストとリントの並列実行
コードの品質チェックを複数のツールで同時に実行させることも可能です。
「このプルリクエストの品質をチェックして」
│
├── サブエージェント 1: 変更されたファイルの型チェック結果を分析
├── サブエージェント 2: 関連するテストの実行結果を確認
└── サブエージェント 3: コーディング規約への準拠状況を確認
コードリサーチの委譲パターン
サブエージェントは並列処理だけでなく、メインエージェントのコンテキストを汚さずにリサーチを行う用途でも威力を発揮します。
大規模コードベースでの探索
数千ファイルを抱える大規模なコードベースでは、目的のコードを見つけるまでに多くのファイルを読む必要があります。これをメインエージェントが直接行うと、コンテキストウィンドウが不要な情報で埋まってしまいます。
サブエージェントに委譲すれば、探索過程のすべてのファイル内容はサブエージェントのコンテキスト内で処理され、メインエージェントには要約された結果だけが返ってきます。
ユーザー: 「このプロジェクトのエラーハンドリングのパターンを教えて」
メインエージェント → サブエージェント:
「プロジェクト内のエラーハンドリングの実装パターンを調査してください。
- どのようなエラー型が定義されているか
- エラーの伝搬方法（throw / return / Result 型など）
- HTTP レスポンスへのマッピング方法
- ログ出力の方法
を特定し、パターンごとに代表的なコード例を示してください。」
サブエージェント: 数十のファイルを読み、パターンを分類して返却
メインエージェント: サブエージェントの結果をもとに、ユーザーにわかりやすく回答
既存の実装パターンの分析
新しい機能を実装するとき、既存のコードベースのパターンに合わせたいことがあります。サブエージェントに「既存の実装パターンを分析してくれ」と依頼することで、メインエージェントはその結果を踏まえた上で新しいコードを生成できます。
たとえば「新しい API エンドポイントを追加したい」という指示に対して、メインエージェントがまずサブエージェントに既存のエンドポイントの実装パターンを調査させ、その結果に基づいてコーディング規約に準拠したコードを生成する、という流れが考えられます。
技術的な事前調査
リファクタリングや設計変更の前に、現状を正確に把握しておく必要があります。サブエージェントに事前調査を委譲することで、メインエージェントは調査結果を受け取ってから最適な方針を決定できます。
ユーザー: 「データベースのクエリをすべて sqlc に移行したい」
メインエージェント → サブエージェント:
「現在のデータベースアクセスコードを調査してください。
- 生 SQL を使っている箇所
- ORM を使っている箇所
- すでに sqlc を使っている箇所
それぞれのファイルパスと件数をまとめてください。」
サブエージェント: リポジトリ全体を探索し、現状を整理して返却
メインエージェント: 移行計画を立案し、優先度をつけてユーザーに提案
大規模リファクタリングでの活用
サブエージェントは、大規模なリファクタリングの計画フェーズで特に力を発揮します。
変更前の現状分析
リファクタリングを始める前に、変更対象の全体像を正確に把握することが重要です。サブエージェントを使えば、複数の観点から同時に現状を分析できます。
「状態管理を Redux から Zustand に移行したい」
│
├── サブエージェント 1: Redux store の構造を分析
│ → slice 一覧、state の型定義、セレクタの数を把握
│
├── サブエージェント 2: Redux に依存しているコンポーネントを列挙
│ → useSelector / useDispatch の使用箇所を特定
│
├── サブエージェント 3: Redux 関連のテストコードを分析
│ → store のモック方法、テストヘルパーの実装を把握
│
└── サブエージェント 4: サードパーティとの Redux 連携を調査
→ redux-persist、RTK Query などの利用状況を確認
メインエージェントはこれらの結果を統合し、移行の難易度や優先順位をユーザーに提示できます。
段階的なリファクタリング計画
大規模なリファクタリングは一度にすべてを変更するのではなく、段階的に進めるのが安全です。サブエージェントの調査結果をもとに、メインエージェントが段階的な移行計画を立てることができます。
たとえば以下のような計画です。
- フェーズ 1: 依存関係が少ないユーティリティ系の slice から移行（影響範囲: 5ファイル）
- フェーズ 2: UI 状態管理の slice を移行（影響範囲: 12ファイル）
- フェーズ 3: API 状態管理を RTK Query から TanStack Query に移行（影響範囲: 20ファイル）
- フェーズ 4: Redux の完全な除去とテストの更新
各フェーズの影響範囲と作業量がサブエージェントの調査で明確になっているため、計画の精度が高くなります。
一貫性の検証
リファクタリングの途中で、すでに変更した箇所と未変更の箇所の一貫性を確認するのも、サブエージェントの得意分野です。「古いパターンがまだ残っている箇所を探して」といった検証作業を委譲できます。
サブエージェントの制限事項
サブエージェントは強力な機能ですが、いくつかの制限があります。正しく理解して使うことが重要です。
読み取り専用の制約
サブエージェントはファイルの読み取りと検索のみが許可されており、ファイルの編集やコマンドの実行はできません。これは安全性を確保するための意図的な設計です。
ファイルの変更が必要な作業は、サブエージェントの調査結果をもとにメインエージェントが実行するという役割分担になっています。
| 操作 | サブエージェント | メインエージェント |
|---|---|---|
| ファイルの読み取り（Read） | 可 | 可 |
| ファイル検索（Grep / Glob） | 可 | 可 |
| ファイルの編集（Edit / Write） | 不可 | 可 |
| コマンド実行（Bash） | 不可 | 可 |
| さらにサブエージェントを起動 | 不可 | 可 |
コンテキストの制限
サブエージェントはメインエージェントの会話履歴を引き継ぎません。Task ツールで渡された指示テキストだけがコンテキストです。そのため、メインエージェントとの対話で暗黙的に共有されている前提情報がサブエージェントには伝わりません。
サブエージェントに指示を出す際は、必要な情報をすべて指示テキストに含めることが重要です。「さっき話した〇〇の件」のような曖昧な参照は機能しません。
トークンコスト
サブエージェントは独立した Claude セッションとして動作するため、それぞれがトークンを消費します。複数のサブエージェントを並列起動すると、その分だけトークンコストが増加します。
ただし、メインエージェントが同じ作業を順番に行う場合と比べて、コンテキストの膨張を避けられるため、結果的にトークン効率が良くなるケースも多くあります。特に大規模なコードベースでの探索作業では、サブエージェントを使ったほうがトータルのトークン消費が少なくなる傾向があります。
起動タイミングの制御
現時点では、サブエージェントの起動タイミングは Claude Code が自動的に判断します。ユーザーが「サブエージェントを使って」と明示的に指示することもできますが、最終的にサブエージェントを使うかどうかは Claude Code の判断に委ねられます。
効果的な使い方のコツ
サブエージェントの効果を最大化するためのコツをいくつか紹介します。
CLAUDE.md での指示
CLAUDE.md ファイルにサブエージェントの活用方針を記載しておくと、Claude Code が適切なタイミングでサブエージェントを使うよう誘導できます。
# ワークフロー管理
## サブエージェント戦略
- メインコンテキストを汚さないためにサブエージェントを積極活用する
- リサーチ・探索・並列分析はサブエージェントにオフロードする
- 複雑な問題にはサブエージェントで計算リソースを投入する
- 1 サブエージェント = 1 タスクで集中実行する
このように方針を明文化しておくことで、Claude Code がサブエージェントを効果的に活用する頻度が高まります。
カスタムスラッシュコマンド（Skills）と組み合わせることで、さらに体系的なサブエージェント活用が可能です。Skills については以下の記事で詳しく解説しています。
タスクの粒度を適切に設定する
サブエージェントに渡すタスクは、具体的かつ独立して完結できる粒度にすることが重要です。
良い例:
- 「
src/auth/ディレクトリ内のすべてのファイルで、JWT トークンの生成と検証がどのように実装されているかを調査してください」 - 「
package.jsonの依存関係を分析し、未使用のパッケージを列挙してください」
避けるべき例:
- 「コードベースを改善してください」（範囲が広すぎる）
- 「前に話した修正の続きをやってください」（コンテキストが不足）
調査と実装を分離する
サブエージェントの最も効果的な使い方は、調査フェーズと実装フェーズを明確に分離することです。
- 調査フェーズ: サブエージェントがコードベースを探索し、現状を把握する
- 判断フェーズ: メインエージェントが調査結果を統合し、最適な方針を決定する
- 実装フェーズ: メインエージェントが方針に基づいてコードを変更する
この流れにより、「よく調べもせずにコードを変更してしまう」というミスを防ぎ、変更の品質を高めることができます。
並列化のヒントを与える
Claude Code がサブエージェントの並列実行を判断しやすいよう、プロンプトで複数の独立した調査項目を明示することも効果的です。
以下の3点を調査してください:
1. 認証ミドルウェアの実装パターン
2. エラーハンドリングの方針
3. テストヘルパーの構造
このように列挙すると、Claude Code は各項目を独立したサブエージェントに割り当てて並列処理する可能性が高くなります。
大規模な変更の前に必ず調査を挟む
大規模な変更を行う前に、必ず「まず現状を調査して」と一言添えることで、サブエージェントによる事前調査が走りやすくなります。
React Router v6 から v7 に移行したい。
まず現状を調査して、移行計画を立ててください。
この指示により、Claude Code はサブエージェントを使って現在のルーティング構成を調査し、その結果をもとに段階的な移行計画を提案してくれます。
まとめ
Claude Code のサブエージェント機能は、開発の速度と品質を同時に向上させる強力な仕組みです。本記事で紹介した内容をまとめます。
- サブエージェントとは: Task ツールによってメインエージェントが子プロセスとして別の Claude Code を起動する仕組み
- 並列処理: 複数のサブエージェントが同時に動作し、調査や分析を並列で進められる
- コンテキスト分離: メインエージェントのコンテキストウィンドウを圧迫せず、効率的にリサーチを進められる
- 読み取り専用: サブエージェントはファイルの読み取りと検索のみ可能で、編集はメインエージェントが担当する
- 効果的な活用法: CLAUDE.md での方針記載、適切なタスク粒度、調査と実装の分離が重要
サブエージェントを意識的に活用することで、大規模なコードベースでの作業効率が格段に向上します。まずは「現状を調査して」と一言添えることから始めて、並列処理の恩恵を体感してみてください。