Claude Code サブエージェント活用ガイド：並列実行と専門化で生産性を上げる

TL;DR

Claude Code のサブエージェントは、メインのコンテキストウィンドウから独立した専門エージェントを起動できる機能です。「調査担当」「セキュリティレビュー担当」「テスト担当」のようにエージェントを役割分担させ、並列実行することで大幅なスピードアップを実現します。

サブエージェントでできること：

• 重い調査タスクを別コンテキストに委譲してメインを軽量に保つ
• 複数の独立した調査・実装を同時並列で実行
• 軽量モデル（Haiku 4.5）をサブに使ってトークンコストを削減
• ツールを限定した読み取り専用のレビュー専用エージェントを定義

---

サブエージェントとは

Claude Code のエージェントループ内には Agent ツールが組み込まれており、Claude は必要と判断した場合や明示的に指示された場合にサブエージェントを起動します。

メインセッション（既定モデル・フルツール）
    ↓ Agent ツールを呼び出す
サブエージェント（Haiku 4.5・Readのみ）
    ↓ 独立したコンテキストで調査・実行
    ↓ 結果のサマリーをメインに返す
メインセッションが結果を受け取り・統合

サブエージェントの特徴：

• 独立したコンテキストウィンドウ ：メインのトークン消費に影響しない
• ツール制限が可能 ：読み取り専用にすることで意図しない変更を防げる
• モデルを変更可能 ：サブには Haiku 4.5 を使ってコスト最適化
• 結果はサマリーのみ返す ：生の実行ログではなく要約が帰ってくる

---

/agents コマンドと組み込みエージェント

定義済みのサブエージェント一覧は /agents で確認できます。同じコマンドから対話UIで新しいエージェントを作成・編集することも可能です。

/agents

Claude Code には以下の組み込みエージェントが最初から用意されており、description のマッチングで自動選択されます。

名前	デフォルトモデル	用途
general-purpose	Sonnet	複数段階のタスク、探索 + 実装の両方が必要なケース
Explore	Haiku	読み取り専用のコードベース検索
Plan	inherit	プランモード中のコードベース調査
claude-code-guide	Haiku	Claude Code / Agent SDK ドキュメントの参照
statusline-setup	Sonnet	ステータスラインのカスタマイズ補助

組み込みは無効化できないので、自作エージェントの name がぶつからないよう避けます。普段は意識せず使えますが、/agents で一覧を眺めておくと「なぜこの調査が Haiku で速く返ってきたのか」が腑に落ちます。

---

エージェント定義ファイルの書き方

エージェント定義は Markdown ファイルで記述します。保存場所はスコープによって異なります。

スコープ	パス
個人（全プロジェクト共通）	~/.claude/agents/<name>.md
プロジェクト	.claude/agents/<name>.md

基本的な定義例

---
name: security-reviewer
description: |
  コードのセキュリティ脆弱性をレビューする専門エージェント。
  認証変更・入力バリデーション・外部 API 連携を含むコードが対象。
  セキュリティ問題の発見に特化し、修正は行わない。
tools: Read Glob Grep
model: claude-haiku-4-5
---

あなたはセキュリティの専門家です。与えられたコードを以下の観点でレビューしてください：

1. SQL インジェクション・XSS・CSRF の可能性
2. 認証・認可ロジックの問題
3. 機密情報のハードコード
4. 入力バリデーションの漏れ
5. 外部 API 呼び出しの安全性

**修正は行わないこと。** 問題の指摘と改善提案のみをレポートとして出力する。

---

フロントマター一覧

フィールド	デフォルト	説明
name	ファイル名	エージェントの識別名
description	—	Claude がいつこのエージェントを使うか判断するための説明（重要）
tools	全ツール	使用を許可するツールをスペース区切りで指定
model	セッションのデフォルト	このエージェント用のモデル（例: claude-haiku-4-5）
isolation	—	worktree を指定すると独立した Git Worktree で実行

---

description の書き方が鍵

description は Claude が「どのサブエージェントをいつ使うか」を自律判断する際の唯一の情報です。具体的かつ明確に書くことが重要です。

# 悪い例
description: コードをレビューする

# 良い例
description: |
  コードの品質とセキュリティをレビューする専門エージェント。
  PR レビューや認証ロジックの変更時に自動的に使用される。
  読み取り専用で動作し、問題の指摘のみを行い修正はしない。

PROACTIVELY / MUST BE USED で発動を強める

複数のサブエージェントが並ぶと、Claude が「どれを呼ぶべきか」迷うケースが出てきます。description 内に以下のキーワードを入れると、自動呼び出しの優先度を引き上げられます。

• PROACTIVELY … 該当条件を見つけたら積極的に使う
• MUST BE USED … 条件にマッチしたら必ず使う

合わせて「どんな状況で使うか」を英語の when 句として書くと Claude のマッチング精度が安定します。

description: |
  Use PROACTIVELY when code changes are detected.
  PR 直前のセキュリティレビュー専門。修正は行わず、指摘のみ返す。

ただし全エージェントに PROACTIVELY を付けると逆に競合が増えます。「定型作業 + コンテキスト分離が効くもの」だけに付けるのが原則で、ワンショットの単純編集では使いません。

---

並列実行でスピードアップ

複数の独立したタスクを並列で処理させることで、直列実行と比べて大幅に時間を短縮できます。

Claude に「これらのタスクを並列で実行してください」と指示すると、自動的に複数のサブエージェントが同時に起動されます。

効果的な並列化の例

コードベース調査（並列化前）：

1. 認証ロジックを調査（5分）
2. DB スキーマを確認（3分）
3. API エンドポイントを一覧化（4分）
合計：12分

コードベース調査（並列化後）：

1. 認証エージェント / DB エージェント / API エージェントを同時起動
合計：5分（最も遅いタスクの時間）

実行のされ方は変わってきている

サブエージェントの動き方は、リリースを重ねるごとに変わっています。押さえておくべき変更点です。

変更	内容
バックグラウンド実行が既定に	サブエージェントは既定でバックグラウンドで走ります。メインセッションを止めずに進みます
fork mode が対話セッションで既定 ON	Claude が fork 型のサブエージェントを要求でき、会話全体とプロンプトキャッシュを引き継ぎます。文脈を渡し直す必要がありません。CLAUDE_CODE_FORK_SUBAGENT=0 で無効化できます
1セッション 200 体の上限が撤廃	総数の制限はなくなりました。ただし同時実行数と入れ子の深さには上限が残ります
入れ子が可能に	バックグラウンドのチェーンは最大5階層まで

fork 既定化の影響が大きい点に注意してください。サブエージェントが会話履歴を持たない前提で書いた定義や運用手順は、見直す価値があります。

並列化に向いているタスク

• 複数モジュールの独立した調査
• 複数ファイルへの同一変更（テスト追加など）
• レビュー + 実装の同時進行（コンフリクトしない場合）
• 異なる技術スタック領域の調査

オーケストレーターパターンで複数エージェントを協調させる

複数のサブエージェントを定義したら、CLAUDE.md でメインエージェントを「指揮者」として振る舞わせる書き方が効きます。「実装してテストしてレビューして」といった指示一発で、ワークフローを自動的に分担して進められます。

# CLAUDE.md
あなたはオーケストレーターです。コード作成依頼を受けたら次の順で進めます。

## ワークフロー
1. 計画フェーズ: 要件を整理し、必要なタスクを洗い出す
2. 実装フェーズ: code-writer に実装を委任
3. テストフェーズ: test-writer にテスト作成を委任
4. レビューフェーズ: code-reviewer と security-reviewer に並列で委任
5. 修正フェーズ: 指摘を踏まえて code-writer / test-writer に再委任
6. 完了報告: 最終差分とレビュー結果をまとめてユーザーに報告

## 各エージェントの責務
- code-writer: 実装のみ
- test-writer: テストの設計と実装
- code-reviewer: 品質・可読性のレビュー
- security-reviewer: セキュリティ観点のレビュー

ポイントは「分岐条件」と「責務の境界」を CLAUDE.md 側で言語化しておくこと。エージェント側のプロンプトで責務を絞り、CLAUDE.md 側でフローを書くと、責務とフローの変更が独立に行えます。

---

実践的な定義例

コードベース探索専門エージェント

---
name: explorer
description: |
  コードベースを読み取り専用で探索する専門エージェント。
  「〜はどこで定義されている？」「〜のフローを追って」のような
  調査タスクに自動的に使用される。ファイルの変更は一切行わない。
tools: Read Glob Grep
model: claude-haiku-4-5
---

あなたはコードベースの調査専門エージェントです。与えられた調査タスクを実行し、
発見した情報をファイルパスと行番号を含めてまとめてください。

調査のみ行い、ファイルの変更・作成・削除は絶対に行わないこと。

テスト生成専門エージェント

---
name: test-writer
description: |
  ユニットテストの生成専門エージェント。
  新しいファイルや関数が追加された後、自動的に呼び出される場合がある。
  既存のテストパターンに合わせたテストを生成する。
tools: Read Glob Grep Write Bash(npm test) Bash(npx jest *)
model: claude-sonnet-4-6
---

あなたはテスト専門のエンジニアです。渡されたコードのユニットテストを書いてください。

1. まず既存のテストファイルを読み、テストパターンを把握する
2. 正常系・異常系・境界値のテストケースを書く
3. モックは必要最小限にする
4. テストを実行して通ることを確認する

テスト対象以外のファイルは変更しないこと。

ドキュメント生成エージェント

---
name: doc-writer
description: |
  コードの JSDoc・TSDoc コメントや README を生成する専門エージェント。
  「ドキュメントを書いて」「コメントを追加して」の指示で使用される。
  コメント・ドキュメントファイルのみを変更し、ロジックには触れない。
tools: Read Glob Grep Edit Write
model: claude-haiku-4-5
---

あなたはドキュメント専門のテクニカルライターです。

- JSDoc / TSDoc 形式でコメントを書く
- コメントは「なぜそう実装されているか」を中心に書く
- 自明な処理にコメントをつけない
- README には実際のコマンド例を必ず含める

ロジックを変更しないこと。コメントとドキュメントのみを編集する。

プロジェクト固有の設計検証エージェント

Linter や型チェッカーで拾えない「設計方針」のレビューにもサブエージェントが使えます。Onion / Clean Architecture のレイヤー境界、ディレクトリ配置規約、依存方向のルールなど、規約として明文化されているがツール化が面倒なものは、読み取り専用エージェントに任せると CI でも回せます。

---
name: architecture-validator
description: |
  Use PROACTIVELY when reviewing code changes.
  Onion Architecture 準拠を検証。レイヤー境界違反やディレクトリ配置のミスを検出し、
  違反箇所（ファイル + 行番号）と修正案だけを返す。修正はしない。
tools: Read Glob Grep
model: claude-sonnet-4-6
---

あなたはアーキテクチャ準拠を検証する専門家です。

## チェック項目
- ディレクトリ配置: Repository は infrastructure/repositories/ にあるか
- レイヤー境界: Domain 層は Infrastructure 層に依存していないか
- ロジック流出: ビジネスロジックが Application / Infrastructure に漏れていないか

## 報告フォーマット
- 違反箇所（ファイルパス + 行番号）
- 違反内容（どのルール違反か）
- 具体的な修正案（コード差分の方向性）

「Domain は Infrastructure を import しない」のような規約は、Linter ルールを書くより自然言語で表現したほうが速く、メンテも楽です。

Worktree 分離で安全な実装エージェント

---
name: experimental-impl
description: |
  実験的な実装を試みる際に使用する隔離エージェント。
  独立した Git Worktree で実行されるため、メインブランチに影響しない。
  「試しに実装してみて」のような探索的なタスクに使用される。
tools: Read Glob Grep Edit Write Bash
isolation: worktree
---

あなたはプロトタイプ実装の専門家です。

与えられた機能を実験的に実装してください。
完成度よりも、動作するプロトタイプを素早く作ることを優先します。
動いたら実装アプローチと学んだことをサマリーとして返してください。

---

Claude Agent SDK での programmatic 定義

サブエージェントは SDK からコード上で定義して実行することもできます。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "セキュリティ観点でこのコードをレビューして",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Agent"],
    agents: {
      "security-reviewer": {
        description: "セキュリティ脆弱性の特定専門エージェント",
        prompt: "SQL インジェクション・XSS・認証バイパスの可能性を調べてレポートする",
        tools: ["Read", "Glob", "Grep"],
        model: "claude-haiku-4-5-20251001"
      }
    }
  }
})) {
  console.log(message);
}

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async for message in query(
    prompt="セキュリティ観点でこのコードをレビューして",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Agent"],
        agents={
            "security-reviewer": AgentDefinition(
                description="セキュリティ脆弱性の特定専門エージェント",
                prompt="SQL インジェクション・XSS・認証バイパスを調べてレポートする",
                tools=["Read", "Glob", "Grep"],
                model="claude-haiku-4-5-20251001"
            )
        }
    )
):
    print(message)

---

コスト最適化の考え方

サブエージェントに適切なモデルを割り当てることでトークンコストを大幅に削減できます。

タスクの種類	推奨モデル	理由
コードベース探索・検索	Haiku 4.5	読み取りのみで軽量モデルで十分
テスト生成・コメント追加	軽量〜標準モデル	定型的な生成タスク
複雑な実装・設計判断	Sonnet 4.6	品質が重要な実装タスク
アーキテクチャ設計・難解な問題	Opus 4.6	高度な推論が必要な場合のみ

---

Subagents vs Agent Teams

2026 年 2 月に登場した Agent Teams はサブエージェントの進化版です。用途に応じて使い分けます。

比較項目	Subagents	Agent Teams
コーディネーション	親エージェントが管理	共有タスクリストで自己調整
コミュニケーション	結果のみ親に返す	チームメンバー同士が直接通信
向いているケース	結果のみが必要な独立タスク	議論・協調が必要な複雑タスク
可視性	親だけが実行状況を把握	全員が進捗を共有
現在のステータス	安定版	実験的機能（要フラグ）

シンプルなタスク分割には Subagents、複数エージェントが相互レビューしながら進めるような高度な協調タスクには Agent Teams を使います。

---

ハマりポイント・注意事項

description の品質がすべて Claude が適切なサブエージェントを自動的に選ぶかどうかは description の質にかかっています。「いつ使うか」を明示的に書いてください。

ツール制限のデフォルトは「全ツール許可」 tools を指定しないとすべてのツールが使えます。読み取り専用エージェントには必ず tools: Read Glob Grep と明示してください。

サブエージェントの実行ログはメインに表示されない サブエージェントがどのファイルを読んだかなどの詳細はメインセッションには表示されません。デバッグ目的では Post-use Hooks でログを出力する方法があります。

isolation: worktree は変更ありで終了した場合のみブランチが残る 変更なしで終了した worktree は自動削除されます。実験的実装の場合は必ず何らかの変更（ファイル作成）を残してください。

モデル名は世代交代が速い 本記事に出てくるモデル名は執筆時点のものです。現在の既定と選択肢は /model で確認してください。コスト最適化の考え方（重いタスクほど高性能モデル、定型タスクほど軽量モデル）自体は世代が変わっても有効です。

---

関連ドキュメント

この記事は Claude Code でのサブエージェントの設定と使い方を扱う。 設計論は別記事にある。

• 分割の判断基準と失敗パターン: サブエージェント設計パターン
• 複数エージェント間のコンテキスト共有: マルチエージェントのコンテキスト設計
• 経路制御とルーティング: マルチエージェントルーティング
• Codex 側の実装: Codex のサブエージェント

参考リンク

• Create custom subagents — Claude Code Docs
• Agent SDK overview — Claude Code Docs
• Agent Teams — Claude Code Docs
• Worktrees — Claude Code Docs