サブエージェント

サブエージェントは、メインの Claude が 専門的なタスクを別の AI に委託する 仕組みです。Claude Code に組み込まれたビルトインエージェントと、自分で定義するカスタムエージェントがあります。

サブエージェントとは

サブエージェントは、特定の役割に特化した「助手」のような存在です。メインの Claude が大きなタスクを処理する際に、一部のタスクをサブエージェントに任せることで効率的に作業を進められます。

メイン Claude:「この機能を実装して」
  ├── 自分で実装する部分
  ├── Explore エージェントに調査を依頼
  ├── Plan エージェントに設計を依頼
  └── 汎用エージェントに並列タスクを依頼

サブエージェントの特徴

メインの Claude から自動的に呼び出される
特定のタスクが完了したら結果をメインに返す
独立したコンテキストで動作する
ツールの使用が制限されている場合がある

ビルトインサブエージェント

Claude Code には、以下のビルトインサブエージェントが用意されています。

1. Explore エージェント

コードベースを 調査・探索 するための専門エージェントです。

Explore エージェントの得意なこと:
  - ファイル構造の調査
  - コードの検索
  - 依存関係の分析
  - 関数やクラスの定義の発見

Explore エージェントは 読み取り専用 で動作します。ファイルの変更は行いません。

2. Plan エージェント

設計や計画 を立案するための専門エージェントです。

Plan エージェントの得意なこと:
  - アーキテクチャの設計
  - 実装計画の策定
  - リファクタリング方針の検討
  - タスクの分解

Plan エージェントも 読み取り専用 で動作します。分析と提案のみを行います。

3. 汎用サブエージェント

特定の役割に限定されない 汎用的なサブエージェント です。メインの Claude が必要に応じて呼び出します。

汎用サブエージェントの用途:
  - 並列タスクの実行
  - 独立した作業の委託
  - 複数ファイルの同時処理

Claude が自動的にサブエージェントを使う

多くの場合、サブエージェントは Claude が自動的に判断して呼び出します。ユーザーが明示的に「サブエージェントを使って」と指示する必要はありません。ただし、「調査してから実装して」のように指示すると、Explore エージェントが活用されやすくなります。

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

プロジェクト固有のサブエージェントを定義できます。

カスタムエージェントの配置

.claude/agents/ ディレクトリにマークダウンファイルを作成します。

my-project/
├── .claude/
│   └── agents/
│       ├── reviewer.md      → レビュー専門エージェント
│       ├── test-writer.md   → テスト作成専門エージェント
│       └── doc-writer.md    → ドキュメント作成エージェント
├── src/
└── ...

カスタムエージェントの書き方

エージェント定義ファイルには、フロントマター（YAML ヘッダー） と プロンプト を記述します。

基本的な構造

markdown

---
name: reviewer
description: コードレビューを行う専門エージェント
tools:
  - Read
  - Glob
  - Grep
---

あなたはコードレビューの専門家です。
以下の観点でコードをレビューしてください:

1. バグの可能性
2. セキュリティの問題
3. パフォーマンスの問題
4. コーディング規約への準拠
5. テストカバレッジ

問題を発見した場合は、具体的な修正案も提示してください。

フロントマターの項目

項目	説明
`name`	エージェントの名前
`description`	エージェントの説明（Claude が役割を理解するために使う）
`tools`	エージェントが使えるツールの一覧
`model`	使用するモデル（省略可）

tools（使用可能なツール）

サブエージェントに与えるツールを制限できます。

yaml

---
tools:
  - Read       # ファイルの読み取り
  - Glob       # ファイルの検索
  - Grep       # テキスト検索
  - Write      # ファイルの書き込み
  - Edit       # ファイルの編集
  - Bash       # コマンドの実行
---

ツールの制限は重要

セキュリティのため、サブエージェントに必要最小限のツールだけを与えましょう。例えば、レビュー用のエージェントには Read、Glob、Grep だけを与え、Write や Bash は与えないことで、安全性を確保できます。

model（使用するモデル）

サブエージェントに使用するモデルを指定できます。

yaml

---
model: claude-sonnet-4-20250514
---

モデルの使い分け

調査・探索系: Sonnet（高速で低コスト）
設計・分析系: Opus（高精度）
実装系: Sonnet（バランスが良い）

コストを抑えるために、すべてのサブエージェントに Opus を使う必要はありません。

カスタムエージェントの実践例

例 1: テスト作成エージェント

.claude/agents/test-writer.md:

markdown

---
name: test-writer
description: ユニットテストを作成する専門エージェント
tools:
  - Read
  - Glob
  - Grep
  - Write
---

あなたはテスト作成の専門家です。

## ルール
- テストフレームワークは Vitest を使用
- テストファイルは __tests__/ ディレクトリに配置
- 正常系、異常系、境界値のテストケースを含める
- モックは vi.mock() を使用
- 既存のテストファイルのスタイルに合わせる

例 2: ドキュメント作成エージェント

.claude/agents/doc-writer.md:

markdown

---
name: doc-writer
description: 技術ドキュメントを作成する専門エージェント
tools:
  - Read
  - Glob
  - Grep
  - Write
---

あなたは技術ドキュメントの作成者です。

## ルール
- JSDoc 形式でコードにコメントを追加
- README.md を最新の状態に保つ
- API ドキュメントはOpenAPI 形式で作成
- 日本語で記述

例 3: セキュリティ監査エージェント

.claude/agents/security-auditor.md:

markdown

---
name: security-auditor
description: セキュリティの問題を検出する専門エージェント
tools:
  - Read
  - Glob
  - Grep
---

あなたはセキュリティ監査の専門家です。
以下の脆弱性を重点的にチェックしてください:
- SQL インジェクション
- XSS（クロスサイトスクリプティング）
- 認証・認可の不備
- 機密情報のハードコーディング
- 依存パッケージの脆弱性