AI Tools 2026年4月15日

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

Claude Code のサブエージェント機能を徹底解説。エージェント定義ファイルの書き方、並列実行によるスピードアップ、モデル・ツール・コンテキストの分離、Claude Agent SDK との連携まで2026年4月の最新仕様でまとめました。

#Claude Code #サブエージェント #Sub-agents #並列実行 #Agent #エージェント設計

TL;DR

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

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

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

サブエージェントとは

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

メインセッション（Sonnet 4.6・フルツール）
    ↓ 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分（最も遅いタスクの時間）

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

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

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

複数のサブエージェントを定義したら、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	読み取りのみで軽量モデルで十分
テスト生成・コメント追加	Haiku 4.5〜Sonnet 4.6	定型的な生成タスク
複雑な実装・設計判断	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 は自動削除されます。実験的実装の場合は必ず何らかの変更（ファイル作成）を残してください。