Claude Codeのサブエージェント機能で並列タスクを自動化する
Claude Codeのサブエージェント機能を使い、複数タスクを並列実行する方法を実践的に解説。大規模コードベースの効率化に役立てよう。
Claude Codeのサブエージェント機能で並列タスクを自動化する
「テストを書きながらドキュメントも更新して、同時にリファクタリングも進めたい」——開発現場でこんな欲張りなシナリオを考えたことはないでしょうか。 通常のAIコーディングアシスタントは、タスクを一つずつ順番に処理するしかありません。 しかしClaude Codeにはサブエージェント（Sub-agent）機能があり、メインエージェントが複数のサブエージェントを生成して並列処理を実現できます。
この記事では、Claude Codeのサブエージェント機能の仕組みから、実際の設定・活用パターンまでを丁寧に解説します。 大規模プロジェクトや複雑なタスクで「AIが思ったより遅い」と感じている方には、特に役立つ内容になっています。
サブエージェントとは何か：仕組みをざっくり理解する
Claude Codeのサブエージェント機能は、Anthropicの公式ドキュメントでも解説されている、エージェントを階層的に分岐させる仕組みです。
通常のClaude Codeは単一のエージェントとして動作します。 ユーザーの指示を受け取り、ファイルを読み書きし、コマンドを実行する——これをシングルスレッドで順番にこなします。
サブエージェント機能を使うと、メインエージェントが「親」となり、複数の「子エージェント（サブエージェント）」を生成します。 各サブエージェントはそれぞれ独立したコンテキストを持ち、別々のタスクを同時進行で処理できます。
イメージとしては次のような構造です：
- メインエージェント（親）
- タスクの分割・委譲・結果の統合を担当
- サブエージェントへの指示出しと進捗監視
- サブエージェント1（子）
- 例：テストコードの自動生成
- サブエージェント2（子）
- 例：READMEとJSDocの更新
- サブエージェント3（子）
- 例：Lintエラーの修正とコードフォーマット
これらが並列で動作することで、従来の3〜5倍の速度でタスクをこなせるケースもあります。
サブエージェントが特に効果を発揮するシナリオ
- 大規模リファクタリング: モジュールAの改修中に、モジュールBのテストを並行して走らせる
- マルチファイル更新: 設定ファイル・ドキュメント・ソースコードを同時に修正する
- CI/CDパイプラインの整備: テスト・ビルド設定・デプロイスクリプトを並列で作成する
- コードレビュー補助: セキュリティチェック・パフォーマンス分析・スタイルチェックを同時実行
サブエージェントを動かすための準備と基本設定
サブエージェント機能を使うには、いくつかの前提条件があります。 順番に確認しましょう。
動作要件の確認
- Claude Codeのバージョン: サブエージェント機能は比較的新しい機能です。最新版を使用してください。
- APIプラン: サブエージェントは複数のAPIコールを同時に発行するため、Anthropic APIの利用上限に注意が必要です。Proプラン以上を推奨します。
- OS: macOS / Linux / Windows（WSL2）のいずれでも動作します。
Claude Codeのインストール確認
ターミナルで以下を実行し、バージョンを確認します。
# Claude Codeのバージョン確認
claude --version
# 最新版へのアップデート（npmの場合）
npm update -g @anthropic-ai/claude-code
バージョンが古い場合はアップデートを行ってください。
CLAUDE.mdにサブエージェントの指針を記述する
サブエージェント機能を安定して使うには、プロジェクトルートのCLAUDE.mdにエージェントへの行動指針を書いておくことが非常に重要です。
これはメインエージェントだけでなく、生成されたサブエージェントにも引き継がれます。
# CLAUDE.md
## プロジェクト概要
このリポジトリはTypeScript製のREST APIサーバーです。
Node.js 20以上、pnpmを使用しています。
## サブエージェント利用時のルール
- ファイルの書き込みは必ずdry-runで確認してから実行すること
- テストは `pnpm test` で実行し、全テストがパスすることを確認すること
- サブエージェントが完了したら、変更ファイルの一覧を報告すること
- 同一ファイルを複数のサブエージェントが同時に編集しないこと（競合回避）
## コーディング規約
- インデント: スペース2つ
- 変数命名: camelCase
- 型定義は必ずTypeScriptで記述する
- コメントは日本語で記述する
## 禁止事項
- `node_modules` 配下への直接書き込み
- `.env` ファイルの内容をログに出力すること
- 本番環境のAPIキーをコードにハードコーディングすること
このCLAUDE.mdを置くことで、サブエージェントが意図しない操作をするリスクを大幅に下げられます。
実践①：テスト自動生成とドキュメント更新の並列実行
最も典型的なサブエージェント活用例として、テストコードの自動生成とドキュメントの更新を並列で行うパターンを紹介します。
シナリオの説明
新しいAPIエンドポイントPOST /users/bulk-importを実装したとします。
このとき以下のタスクが発生します：
src/users/bulk-import.test.tsに単体テストを追加するdocs/api-reference.mdにエンドポイントのリファレンスを追加するsrc/users/bulk-import.tsのJSDocコメントを整備する
これらを一つのサブエージェント指示でまとめて依頼するのが基本的な使い方です。
Claude Codeへの指示例
Claude Codeのチャット画面（またはターミナル）に、以下のように指示します。
以下の3つのタスクをサブエージェントで並列処理してください。
【タスク1: テストコード生成】
- 対象ファイル: src/users/bulk-import.ts
- テストファイル: src/users/bulk-import.test.ts を新規作成
- 正常系（200）・バリデーションエラー（400）・認証エラー（401）・
重複データエラー（409）のケースを網羅してください
- テストフレームワークはVitestを使用
【タスク2: APIドキュメント更新】
- 対象ファイル: docs/api-reference.md
- エンドポイント「POST /users/bulk-import」のセクションを追加
- リクエスト/レスポンスのスキーマをJSONサンプル付きで記載すること
【タスク3: JSDocコメント整備】
- 対象ファイル: src/users/bulk-import.ts
- 関数・型・パラメータに日本語のJSDocコメントを追加
- @param, @returns, @throws を必ず記述すること
各タスクが完了したら、変更したファイル名と変更内容の要約を報告してください。
実行中の動作確認
Claude Codeがサブエージェントを起動すると、ターミナル上に以下のような出力が表示されます。
[Main Agent] タスクを3つのサブエージェントに分割します
[Sub-agent 1] 起動中... src/users/bulk-import.test.ts を分析
[Sub-agent 2] 起動中... docs/api-reference.md を分析
[Sub-agent 3] 起動中... src/users/bulk-import.ts を分析
[Sub-agent 3] 完了: JSDocコメントを14箇所に追加しました
[Sub-agent 1] 完了: 8件のテストケースを生成しました（全テストパス確認済み）
[Sub-agent 2] 完了: APIリファレンスに「POST /users/bulk-import」セクションを追加しました
[Main Agent] 全サブエージェントの処理が完了しました
変更ファイル:
- src/users/bulk-import.ts
- src/users/bulk-import.test.ts（新規）
- docs/api-reference.md
並列処理により、順番に実行した場合と比べて処理時間を約60%短縮できるケースがあります。
実践②：大規模リファクタリングをサブエージェントで分割統治する
次は、より高度な活用例を見ていきましょう。 モノリシックなコードベースをモジュール分割するというシナリオです。
課題の背景
1,000行を超えるような大きなファイルsrc/app.tsがあるとします。
これを以下のように分割したいとします：
src/routes/——ルーティング定義src/middlewares/——ミドルウェア群src/controllers/——コントローラー層src/services/——ビジネスロジック層
安全に進めるための事前準備
大規模な変更を行う前に、必ずGitブランチを切ってください。
# 作業ブランチを作成
git checkout -b refactor/split-app-module
# 現状をコミット（リセットポイントとして）
git add -A && git commit -m "refactor: サブエージェントによるモジュール分割の開始前スナップショット"
このブランチを起点にClaude Codeを起動することで、万が一の際にgit resetで元に戻せます。
フェーズを分けたサブエージェント指示
大規模リファクタリングは、一度にすべてを依頼するより、フェーズを分けた方が安全です。
フェーズ1: 分析と設計（サブエージェント1体）
まず分析フェーズを実行してください。
src/app.ts を読み込み、以下の情報を抽出・整理して報告してください。
1. 定義されている全ルート（メソッド・パス・ハンドラ名）の一覧
2. 定義されているミドルウェアの一覧
3. ビジネスロジックを含む関数の一覧
4. 推奨するファイル分割の設計案
※ この段階ではファイルの書き込みは行わないでください。
フェーズ2: 実装（複数サブエージェントで並列）
フェーズ1の結果を確認した上で、実装フェーズに進みます。
フェーズ1の分析結果をもとに、以下の4タスクをサブエージェントで並列実行してください。
各サブエージェントは独立したファイルのみを担当し、他のサブエージェントのファイルには触れないこと。
【タスク1: ルーティング層の分離】
- src/routes/user.routes.ts を新規作成
- src/routes/product.routes.ts を新規作成
- src/app.ts から対応するルート定義を移動
【タスク2: ミドルウェア層の分離】
- src/middlewares/auth.middleware.ts を新規作成
- src/middlewares/error.middleware.ts を新規作成
- src/app.ts から対応するコードを移動
【タスク3: コントローラー層の分離】
- src/controllers/user.controller.ts を新規作成
- src/controllers/product.controller.ts を新規作成
【タスク4: サービス層の分離】
- src/services/user.service.ts を新規作成
- src/services/product.service.ts を新規作成
完了後、各タスクについて「追加した行数」「移動した行数」「削除した行数」を報告すること。
フェーズ3: 統合と検証（メインエージェント）
すべてのサブエージェントの完了を確認した後、以下を実行してください。
1. src/app.ts を各モジュールをimportする形に書き換える
2. pnpm build を実行してビルドエラーがないか確認
3. pnpm test を実行してすべてのテストがパスすることを確認
4. エラーがあれば修正してから完了とする
このように分析→実装→検証の3フェーズに分けることで、大規模なリファクタリングも安全に進められます。
サブエージェント活用時の注意点とトラブルシューティング
サブエージェントは強力ですが、使い方を誤るとかえって問題が生じることもあります。 よくあるトラブルとその対処法を確認しておきましょう。
注意点①：競合書き込みを避ける
最も重要な注意点は、複数のサブエージェントが同じファイルを同時に編集しないようにすることです。 同一ファイルへの並列書き込みは、内容の上書きや破損を引き起こす可能性があります。
指示を出す際には「各サブエージェントの担当ファイルを明示的に分ける」ことを必ず意識してください。
前述のCLAUDE.mdに「同一ファイルを複数エージェントで同時編集禁止」と記述しておくと、より安全です。
注意点②：APIトークン消費量の管理
サブエージェントはそれぞれが独立したAPIコールを行うため、トークン消費量が単純計算でエージェント数倍になります。
コスト管理のために以下を心がけましょう：
- サブエージェントを4〜5体以上生成するタスクは慎重に
- 各サブエージェントへのコンテキスト（渡すファイル内容）を必要最小限にする
- Anthropic APIの料金ページでトークン単価を事前に確認する
注意点③：サブエージェントのハングアップ
稀にサブエージェントが応答を返さずにハングアップすることがあります。
その場合はCtrl + CでClaude Codeを中断し、以下の手順で状態を確認してください。
# Gitの差分で変更済みファイルを確認
git status
git diff --stat
# 変更内容を確認してから部分的にステージング
git add src/routes/user.routes.ts
git diff --cached
中断した時点までの変更は残っているため、完了済みのサブエージェントの成果物は保持されています。 未完了のタスクだけ再度指示を出し直せばOKです。
注意点④：結果の検証を怠らない
サブエージェントが「完了しました」と報告しても、必ずビルドとテストを実行して検証してください。 AIが生成したコードには微妙なミスが混入していることがあります。
# TypeScriptのビルド確認
pnpm build
# テスト実行
pnpm test
# Lintチェック
pnpm lint
これらがすべてパスしてから初めて「タスク完了」とみなすようにしましょう。
サブエージェントをさらに活用するための上級テクニック
基本的な使い方をマスターしたら、次のステップとしてより高度な活用パターンを試してみましょう。
テクニック①：タスク依存関係の明示
サブエージェントのタスクに依存関係がある場合（Aが終わってからBを実行したい、など）、指示の中に依存関係を明記します。
以下の順序でサブエージェントを実行してください。
【フェーズA（並列）】
- サブエージェント1: データベーススキーマのマイグレーションファイルを生成
- サブエージェント2: 既存のモックデータをフィクスチャとして整理
【フェーズB（フェーズA完了後に開始）】
- サブエージェント3: フェーズAのマイグレーション適用後のDBスキーマを
読み込み、新しいREST APIエンドポイントを実装
このように「フェーズA完了後」という条件を明示することで、依存関係のある処理も安全に並列化できます。
テクニック②：コードレビューをサブエージェントに分担させる
人間のレビューに加えて、複数の観点からのAIレビューをサブエージェントで並列実行するパターンも非常に効果的です。
PRの差分ファイル（git diff HEAD~1）を読み込み、
以下の3つの観点でそれぞれサブエージェントがレビューを行ってください。
【サブエージェント1: セキュリティレビュー】
- SQLインジェクション・XSS・CSRF・認証バイパスの可能性をチェック
- 機密情報のハードコーディングがないか確認
【サブエージェント2: パフォーマンスレビュー】
- N+1クエリの可能性をチェック
- 不要なループや重複処理がないか確認
- キャッシュ戦略の改善提案
【サブエージェント3: テストカバレッジレビュー】
- 新しいコードにテストが存在するか確認
- エッジケースのテストが抜けていないか確認
各レビューの結果をMarkdown形式でまとめて報告してください。
これにより、セキュリティ・パフォーマンス・テストの3軸で網羅的なレビューが短時間で完了します。
テクニック③：サブエージェントの成果物を集約する
サブエージェントが各自レポートやコードを生成した後、メインエージェントに集約・整形を依頼するパターンも有効です。
3つのサブエージェントがそれぞれ生成した以下のファイルを統合してください。
- SECURITY_REVIEW.md（セキュリティレビュー結果）
- PERFORMANCE_REVIEW.md（パフォーマンスレビュー結果）
- TEST_REVIEW.md（テストカバレッジレビュー結果）
これらを REVIEW_REPORT.md として統合し、
「Critical」「Warning」「Info」の3段階で優先度付きに整理してください。
分散した情報を一つのドキュメントに集約することで、チームへの共有も簡単になります。
まとめ：サブエージェントで開発速度を次のレベルへ
Claude Codeのサブエージェント機能は、大規模で複雑な開発タスクを分割統治するための強力なアプローチです。 今回解説した内容を振り返りましょう。
- サブエージェントの仕組み: メインエージェントが複数の子エージェントを生成し、並列処理を実現する
- CLAUDE.mdの重要性: サブエージェントへの行動指針を事前に記述することで安全性が高まる
- 実践①: テスト生成・ドキュメント更新・JSDoc整備を並列実行して時間を短縮する
- 実践②: 大規模リファクタリングをフェーズ分けして安全に並列化する
- 注意点: 競合書き込みの回避・トークン消費の管理・結果の必ず検証
- 上級テクニック: タスク依存関係の明示・並列コードレビュー・成果物の集約
次のアクション
まずは小さく始めることをお勧めします。
今のプロジェクトで「同時に進めたいけれど手が回らない」タスクを2〜3個ピックアップして、サブエージェントに並列実行を依頼してみましょう。
最初は2つのサブエージェントから試し、慣れてきたら3〜5つの並列処理へとスケールアップしていくのがスムーズです。
CLAUDE.mdに適切なルールを記述しておくことで、安全かつ効率的にサブエージェントを活用できます。
ぜひ試してみてください。