Claude Code の Sub-agent パターン — 複雑なタスクを自律的に分解・並列処理する設計手法

「この変更、全ファイルに反映しておいて」——Claude Code にそう指示した瞬間、ターミナルに見慣れない表示が流れます。⏳ Launching agent... の文字列が3つ同時に現れ、それぞれが別のディレクトリで作業を始めています。これが Sub-agent パターンです。

Claude Code は単一のプロンプト→レスポンスで完結するツールではありません。内部で複数の「子エージェント」を起動し、タスクを分解して並列処理できます。この仕組みを理解しているかどうかで、同じ Claude Code を使っていても生産性に2〜3倍の差が出る。

Sub-agent はいつ、なぜ生まれるのか

Claude Code が Sub-agent を生成するのは、単一のコンテキストでは処理しきれないと判断した場合です。具体的には以下の3条件のいずれかを満たすとき:

探索範囲が広い: grep や find で複数ディレクトリを横断する必要がある
変更対象が多い: 10ファイル以上の同時編集が見込まれる
独立した検証が必要: テスト実行とリファクタリングを並行して進められる

重要なのは、Sub-agent の生成はユーザーが明示的に指示するものではないという点です。Claude Code が自律的に判断します。ただし、プロンプトの書き方で Sub-agent が生成されやすくなるパターンがある:

# Sub-agent が生成されにくい指示
claude "src/utils/format.ts の formatDate 関数を修正して"
 
# Sub-agent が生成されやすい指示
claude "全てのコンポーネントで日付フォーマットが統一されていない問題を修正して。
影響範囲を調査し、テストも更新すること"

後者のように「調査」「全て」「テストも」といったキーワードが含まれると、Claude Code はタスクを分割可能と判断しやすくなります。私の経験では、指示文に動詞が3つ以上含まれると Sub-agent 率が跳ね上がる。

タスク分解の粒度を CLAUDE.md で制御する

Sub-agent の挙動を最も効果的にコントロールできるのが CLAUDE.md です。プロジェクトルートに配置するこのファイルで、タスクの分解方針を事前に定義できます。

# CLAUDE.md — Sub-agent 制御セクション
 
## タスク分解ポリシー
- テスト修正は本体修正と並列で実行してよい
- データベースマイグレーションは必ず直列処理（並列禁止）
- フロントエンドとバックエンドの変更は別 Sub-agent に分割可
 
## ディレクトリ別オーナーシップ
- src/api/ — バックエンド担当。変更時は必ず integration test を実行
- src/components/ — フロントエンド担当。Storybook の snapshot 更新を含む
- prisma/ — DB担当。マイグレーション生成後に seed データとの整合性を確認

このように記述しておくと、Claude Code は Sub-agent を生成する際にこのポリシーを参照します。「データベースマイグレーションは直列」と書いておけば、たとえ並列処理可能な状況でも順番に実行してくれます。

実際のプロジェクトで私が使っている CLAUDE.md のパターンを紹介する:

## 並列処理のガードレール
- 同一ファイルへの書き込みを複数 Sub-agent に許可しない
- package.json の変更は最後に1回だけ実行
- git commit は全 Sub-agent の完了後にまとめて行う

この「ガードレール」セクションがないと、2つの Sub-agent が同時に package.json を編集してコンフリクトが起きることがあります。これは公式ドキュメントには書かれていないが、実際の大規模プロジェクトで必ずぶつかる壁です。

並列 Sub-agent の結果統合パターン

Sub-agent が並列で動いた後、その結果をどう統合するかが最も難しい部分です。Claude Code は内部で以下の3段階プロセスを実行している:

Phase 1: 各 Sub-agent の差分収集

各 Sub-agent が生成した変更をファイル単位で収集します。この時点では衝突検出は行われません。

Phase 2: 衝突検出と解決

同一ファイルを複数の Sub-agent が変更した場合、親エージェントが差分をマージします。ここで git の3-way merge に似たロジックが使われるが、セマンティックな理解を伴うため、単純なテキストマージよりも賢い判断ができます。

Phase 3: 整合性検証

統合後のコードに対して、型チェックやリントを自動実行します。エラーがあれば修正用の Sub-agent が追加で起動されます。

この流れを活用するために、私はプロジェクトに以下のスクリプトを用意している:

{
  "scripts": {
    "validate": "tsc --noEmit && eslint . && vitest run --reporter=verbose",
    "validate:quick": "tsc --noEmit && eslint --cache ."
  }
}

validate コマンドを package.json に定義しておくと、Claude Code の Phase 3 で自動的に使われます。validate:quick も用意しておくと、中間チェック時にはこちらが使われてフィードバックループが速くなります。

実践: モノレポでの Sub-agent 活用

モノレポ構成のプロジェクトで Sub-agent パターンが最も威力を発揮します。以下は Turborepo + Claude Code の組み合わせで、フロントエンドとバックエンドを同時にリファクタリングした実例です:

プロジェクト構成:
packages/
  api/        ← Sub-agent A が担当
  web/        ← Sub-agent B が担当
  shared/     ← 親エージェントが直接管理（共有コード）

指示文:

認証フローを JWT から Session ベースに移行して。
API サーバーのミドルウェア、フロントエンドの認証コンテキスト、
共有の型定義を全て更新すること。テストも修正して。

この指示に対して Claude Code は以下のように分解した:

親エージェント: packages/shared/ の型定義を先に更新
Sub-agent A: packages/api/ のミドルウェアとテストを更新（shared の変更を参照）
Sub-agent B: packages/web/ の認証コンテキストとテストを更新（shared の変更を参照）

ポイントは、共有コードの変更が先に行われ、それを参照して各 Sub-agent が動く「依存関係を考慮した並列処理」になっていることです。完全な並列ではなく、DAG（有向非巡回グラフ）に基づいた実行順序になります。

Sub-agent のデバッグと監視

Sub-agent が期待通りに動かない場合のデバッグ方法も押さえておきたい。

# Claude Code のログを詳細モードで確認
CLAUDE_LOG_LEVEL=debug claude "タスク内容"

ログには各 Sub-agent の起動タイミング、割り当てられたタスク、実行時間が記録されます。ここで注目すべきは agent_context_tokens フィールドです。これが親エージェントのコンテキスト長に近い場合、Sub-agent に十分な情報が渡されていない可能性があります。

もう一つ実用的なテクニックとして、--max-turns フラグがある:

# Sub-agent の最大ターン数を制限（デフォルトは無制限）
claude --max-turns 20 "大規模リファクタリングを実行"

Sub-agent が無限ループに陥る稀なケースに対する安全弁です。通常は不要だが、CI/CD パイプラインに Claude Code を組み込む場合は設定しておくことを勧める。

コスト最適化: Sub-agent と Token 消費

Sub-agent パターンを使うとトークン消費が増える点は意識しておく必要があります。各 Sub-agent が独自のコンテキストを持つため、プロジェクトの基本情報（CLAUDE.md の内容、ディレクトリ構造など）が重複して消費されます。

経験上の目安:

Sub-agent なし: 基準コスト × 1.0
Sub-agent 2並列: 基準コスト × 1.6〜1.8（重複コンテキスト分）
Sub-agent 3並列: 基準コスト × 2.2〜2.5

コストを抑えるには、CLAUDE.md を簡潔に保つことが効果的です。Sub-agent は全員が CLAUDE.md を読み込むため、1,000 トークン削減すれば Sub-agent 3つで 3,000 トークンの節約になります。

# ❌ 冗長な CLAUDE.md（Sub-agent コスト増）
このプロジェクトは2024年1月に開始され、チームメンバーは5人で...
（背景説明が500行）
 
# ✅ 簡潔な CLAUDE.md（Sub-agent コスト最適化）
## 技術スタック
Next.js 15 / TypeScript / Prisma / PostgreSQL
 
## ルール
- テストは vitest。カバレッジ80%以上を維持
- API変更時は OpenAPI spec も更新

次のステップ

Sub-agent パターンを自分のプロジェクトで試すなら、まずは CLAUDE.md に「タスク分解ポリシー」セクションを追加することから始めてほしい。それだけで Claude Code の自律的なタスク分解が格段に賢くなります。