Claude Codeのサブエージェント活用 - 並列タスクで開発を加速

Claude Codeのサブエージェント（Agent tool）は、メインの会話とは独立したコンテキストウィンドウでタスクを実行する仕組み。大規模な調査やコードレビューを並列で処理することで、開発ワークフローを高速化できる。

サブエージェントとは

サブエージェントは、Claude Codeのメイン会話から委任された特定タスクを独立して処理するAIアシスタント。以下の特性を持つ。

特性説明
コンテキスト分離独自のコンテキストウィンドウで動作し、メイン会話のコンテキストを消費しない
カスタムプロンプトタスクに特化したシステムプロンプトを設定可能
ツール制限アクセスできるツールを限定できる（最小権限の原則）
結果の要約実行結果はサマリーとしてメイン会話に返却される

スキルとの違い

比較項目スキル（Skill）サブエージェント
目的再利用可能な知識・ワークフロー独立したタスク実行
コンテキストメイン会話と共有（context: forkで分離も可）常に分離
適したケース参照情報、定型ワークフロー大量ファイル読み込み、並列作業、専門タスク
結果の返却直接メイン会話に反映サマリーとして返却

サブエージェントの種類

組み込みサブエージェント

Claude Codeには、用途に応じた組み込みサブエージェントタイプがある。

タイプ用途使用例
general-purpose汎用タスクコード分析、ドキュメント生成、調査
Exploreコードベースの探索・調査依存関係の追跡、アーキテクチャの把握
Planタスク計画の策定実装計画の立案、影響範囲の分析

カスタムサブエージェント

プロジェクト固有のサブエージェントをMarkdownファイルで定義できる。frontmatterで名前、説明、使用ツール、モデルなどを設定する。

---
name: code-quality-reviewer
description: コード品質のレビューを行うエージェント
model: inherit
tools: ["Read", "Grep", "Glob"]
---

あなたはコード品質レビューの専門家です。
以下の観点でコードを分析してください:
1. 可読性・保守性
2. セキュリティ脆弱性
3. プロジェクトのコーディング規約への準拠

ツール制限のパターン

用途に応じてサブエージェントがアクセスできるツールを制限する。

# 読み取り専用（分析・調査向け）
tools: ["Read", "Grep", "Glob"]

# コード生成向け
tools: ["Read", "Write", "Grep"]

# テスト実行向け
tools: ["Read", "Bash", "Grep"]

# 全ツールへのアクセス（省略またはワイルドカード）
tools: ["*"]

生成可能なサブエージェントの制限

メインエージェントが生成できるサブエージェントの種類を制限することも可能。

---
name: coordinator
description: 専門エージェントに作業を振り分けるコーディネーター
tools: Agent(worker, researcher), Read, Bash
---

この設定では worker と researcher のみ生成可能になる。Agent とだけ書けば全種類のサブエージェントを生成できる。

Agent toolの呼び出し方法

サブエージェントはAgent tool（Task tool）を通じて呼び出す。JSON形式でパラメータを指定する。

基本構造

{
  "subagent_type": "general-purpose",
  "description": "タスクの簡潔な説明",
  "prompt": "サブエージェントへの詳細な指示"
}

パラメータ一覧

パラメータ型必須説明
subagent_typestring○サブエージェントの種類
descriptionstring○タスクの概要（メイン会話に表示される）
promptstring○サブエージェントへの具体的な指示

呼び出し例

{
  "subagent_type": "general-purpose",
  "description": "認証モジュールのセキュリティレビュー",
  "prompt": "src/auth/ ディレクトリ配下のコードを読み、以下の観点でセキュリティレビューを実施してください:\n1. 入力バリデーションの漏れ\n2. SQLインジェクションのリスク\n3. 認証トークンの取り扱い\n4. エラーメッセージからの情報漏洩\n\n問題箇所はファイル名と行番号を含めて報告してください。"
}

並列実行

サブエージェントの真価は並列実行にある。独立したタスクを同時に走らせることで、逐次実行に比べて大幅な時間短縮が可能。

並列実行の条件

並列実行が適しているケース:

  • 各タスクが互いに依存しない
  • それぞれのタスクが異なるファイルや領域を対象とする
  • 結果の統合が容易

逐次実行が適しているケース:

  • 前のタスクの結果が次のタスクの入力になる
  • 同じファイルを編集する可能性がある
  • タスク間で依存関係がある

バックグラウンド実行（run_in_background）

run_in_background パラメータを使うことで、サブエージェントをバックグラウンドで実行できる。メイン会話はブロックされず、結果は完了時に通知される。

"このタスクをバックグラウンドで実行してください:
src/components/ 配下の全コンポーネントのprops定義を一覧化する"

バックグラウンド実行の特徴:

項目説明
メイン会話ブロックされない。他の作業を継続可能
結果通知完了時に自動通知
ポーリング不要完了を待つための sleep やポーリングは不要
用途時間のかかる調査、テスト実行、大量ファイル処理

ワークツリー分離（isolation: worktree）

複数のサブエージェントが同じリポジトリのファイルを変更する場合、Gitワークツリーによる分離が有効。各サブエージェントが独立したワークツリーで作業することで、ファイル競合を防ぐ。

仕組み

メインワークツリー（main）
├── サブエージェントA用ワークツリー（自動作成）
├── サブエージェントB用ワークツリー（自動作成）
└── サブエージェントC用ワークツリー（自動作成）

設定方法

カスタムサブエージェントのfrontmatterで isolation: worktree を指定する。

---
name: feature-implementer
description: 機能を実装するエージェント
isolation: worktree
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
---

自然言語でClaude Codeに「ワークツリーを使ってエージェントを実行して」と指示することもできる。

ワークツリーのライフサイクル

フェーズ動作
作成サブエージェント起動時に自動作成
使用中サブエージェントが独立したディレクトリで作業
完了（変更なし）ワークツリーは自動削除
完了（変更あり）ワークツリーは保持され、手動でマージ可能

実用的な活用パターン

パターン1: 並列コードレビュー

複数の観点からコードレビューを同時に実行する。

以下の4つのエージェントを並列で実行してください:

エージェント1: CLAUDE.md準拠チェック（変更ファイルがCLAUDE.mdのルールに従っているか）
エージェント2: セキュリティレビュー（diffに含まれるセキュリティ上の問題）
エージェント3: バグ検出（diff内のロジックエラーや明らかなバグ）
エージェント4: パフォーマンス分析（N+1クエリ、不要な再レンダリング等）

各エージェントが独立した観点でレビューするため、並列実行に最適なパターン。

パターン2: 大規模コードベースの調査

複数のサブエージェントに異なる領域の調査を委任する。

以下のタスクを並列で調査してください:

1. src/api/ 配下でエラーハンドリングが不統一な箇所を列挙
2. src/components/ 配下で未使用のpropsが定義されているコンポーネントを列挙
3. src/utils/ 配下で重複したユーティリティ関数を検出

パターン3: テストの並列実行と分析

以下を並列で実行してください:

エージェント1: ユニットテストを実行し、失敗したテストの原因を分析
エージェント2: E2Eテストを実行し、失敗箇所のスクリーンショットを確認
エージェント3: カバレッジレポートを生成し、カバレッジが低いモジュールを特定

パターン4: ドキュメント生成

以下のドキュメントを並列で生成してください:

エージェント1: src/api/ のエンドポイント一覧とリクエスト/レスポンス仕様
エージェント2: src/components/ のコンポーネントカタログ（props一覧）
エージェント3: データベーススキーマからER図の記述を生成

パターン5: マルチエージェント協調（コーディネーターパターン）

コーディネーターエージェントが複数のワーカーエージェントにタスクを分配する構成。

---
name: coordinator
description: タスクを専門エージェントに振り分けるコーディネーター
tools: Agent(database-worker, api-worker, frontend-worker), Read, Bash
---

あなたはプロジェクトのコーディネーターです。
受け取ったタスクを分析し、適切な専門エージェントに作業を委任してください。
依存関係がないタスクは並列で実行してください。

各ワーカーの状態ファイルで進捗を管理する構成も可能。

---
agent_name: database-worker
task_number: 4.2
dependencies: ["Task 4.1"]
additional_instructions: "PostgreSQLを使用"
---

# タスク: データベーススキーマ実装

## 要件
- マイグレーションファイルの作成
- インデックスの追加
- テストの実装

パターン6: コンテキストウィンドウの節約

メインの会話コンテキストが大きくなった場合、新しい調査タスクをサブエージェントに委任することで、メインコンテキストの圧迫を防ぐ。

サブエージェントで以下を調査してください:
このプロジェクトで使われているすべてのサードパーティライブラリのバージョンを
package.jsonから読み取り、各ライブラリの最新バージョンと比較して
アップデートが必要なものをリストアップしてください。

サブエージェントが大量のファイルを読み込んでも、メイン会話には要約のみが返るため、コンテキストを効率的に使える。

サブエージェント活用時の注意点

コンテキストの共有範囲

共有される情報共有されない情報
明示的にプロンプトで渡した指示メイン会話の過去のやり取り
ファイルシステムへのアクセスメイン会話のコンテキストウィンドウ内容
CLAUDE.mdのルール他のサブエージェントの結果（明示的に渡さない限り）

サブエージェントはメイン会話の文脈を持たないため、必要な情報はすべてプロンプトに含める必要がある。

コストへの影響

サブエージェントはそれぞれ独立したAPI呼び出しを行う。

  • 並列実行: 各サブエージェントのトークン消費が加算される
  • モデル選択: カスタムサブエージェントで model を指定すれば、タスクに応じて軽量モデルを使用してコストを抑えられる
  • コスト最適化: 読み取り専用の調査は軽量モデル、コード生成やバグ検出は高性能モデルを使い分ける
# 軽量タスク向け
---
name: simple-analyzer
model: sonnet
tools: ["Read", "Grep", "Glob"]
---

# 高精度が必要なタスク向け
---
name: bug-detector
model: opus
tools: ["Read", "Grep", "Glob", "Bash"]
---

プロンプト設計のポイント

サブエージェントの効果を最大化するには、プロンプトの質が重要。

ポイント良い例悪い例
具体的な対象指定src/auth/ 配下のファイルを分析コードを分析
出力形式の指定ファイル名・行番号付きで報告問題があれば教えて
スコープの限定diffに含まれる変更のみ対象プロジェクト全体をチェック
判断基準の明示CWE Top 25に基づいて評価セキュリティを確認

並列実行の制約

  • 同じファイルを複数のサブエージェントが同時に編集すると競合が発生する（ワークツリー分離で回避可能）
  • サブエージェント同士は直接通信できない（コーディネーターを介する必要がある）
  • 大量のサブエージェントを同時起動するとリソース消費が増大する

まとめ表: サブエージェントの選択ガイド

シナリオ推奨構成理由
独立した調査を複数実行並列サブエージェント（読み取り専用）互いに依存しないため並列可能
複数ファイルの同時編集ワークツリー分離 + 並列ファイル競合を防止
長時間かかる分析バックグラウンド実行メイン会話をブロックしない
コンテキストが逼迫サブエージェントに委任メインコンテキストを節約
段階的なタスク逐次実行前のタスクの結果に依存
大規模プロジェクトコーディネーターパターンタスク分配と進捗管理

参考リンク