Claude Code サブエージェント完全ガイド｜作成・設定・並列実行まで実例つきで解説

Claude Codeで大規模なコードベースを扱うと、コンテキストウィンドウがすぐに圧迫されます。テスト実行のログ、ファイル探索の結果、レビュー出力——これらがメイン会話に蓄積すると、Claude の応答品質が低下していきます。

サブエージェントは、この問題を「独立したコンテキストウィンドウで専門タスクを処理する」というアプローチで解決する機能です。メインの会話を汚さずに、調査・テスト・レビューなどの作業を委任し、要約だけを受け取れます。

サブエージェントの仕組み

サブエージェントは、Claude Codeが特定のタスクを委任できる専門AIアシスタントです。それぞれが独自のコンテキストウィンドウ、カスタムシステムプロンプト、ツールアクセス設定、権限設定を持ちます。

動作の流れは次のとおりです。

1. ユーザーがClaude Codeに指示を出す
2. Claude Codeがタスク内容とサブエージェントのdescriptionを照合する
3. 適切なサブエージェントにTask()ツールでタスクを委任する
4. サブエージェントが独立したコンテキストで処理を実行する
5. 結果がメイン会話に要約として返される

重要な制約として、サブエージェントは他のサブエージェントを生成できません。ネストされた委譲が必要な場合は、メイン会話から複数のサブエージェントをチェーンするか、Skillsを使用する必要があります。

組み込みサブエージェントの種類と役割

Claude Codeには、あらかじめ用意された組み込みサブエージェントがあります。

Exploreは最もよく使われる組み込みサブエージェントです。Haikuモデルで動作するため高速かつ低コストで、コードベースの検索に最適化されています。呼び出し時には徹底度レベル（quick / medium / very thorough）が指定され、検索の深さが調整されます。

カスタムサブエージェントの作り方

/agents コマンドによる対話的作成

最も手軽な方法は/agentsコマンドです。

/agents

表示されるメニューから以下の手順で進めます。

1. 「Create new agent」を選択
2. スコープ（User-level / Project-level）を選択
3. 作成方法を選ぶ（Claude生成 or 手動）
4. エージェントの説明を入力
5. 使用ツールを選択
6. モデルを選択
7. 背景色を選択して保存

保存後すぐに利用可能になり、セッションの再起動は不要です。

Markdownファイルによる手動作成

YAML frontmatterを含むMarkdownファイルを直接作成する方法もあります。ファイルの前半がメタデータ・設定、後半がシステムプロンプトになります。

---
name: security-auditor
description: セキュリティ観点でコードを監査する。コード変更後に自動的に使用する。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたはセキュリティ監査の専門家です。
呼び出されたら、以下の観点でコードを分析してください。

1. SQLインジェクション・XSSなどOWASPトップ10の脆弱性
2. 認証・認可の不備
3. シークレット情報のハードコーディング
4. 入力バリデーションの欠如
5. 依存パッケージの既知脆弱性

重要度（Critical / Warning / Info）別に整理して報告してください。

配置場所と優先度

サブエージェントの配置場所によってスコープと優先度が異なります。

チーム開発では.claude/agents/に配置してGitリポジトリにコミットすることで、メンバー全員が同じサブエージェントを共有できます。個人用のカスタマイズは~/.claude/agents/に配置するのが適切です。

frontmatterフィールド一覧と設定テンプレート

frontmatterで指定可能なフィールドの全一覧です。nameとdescriptionのみが必須で、それ以外はすべてオプションです。

権限モードの選択肢

bypassPermissionsはすべてのチェックを無視するため、信頼できるサブエージェントにのみ使用してください。

実践的なサブエージェント設定例

テスト実行＆レポーター

テスト実行結果の大量ログをメインコンテキストから分離し、失敗テストの要約だけを返すパターンです。

---
name: test-runner
description: テストスイートを実行し、失敗テストのみ報告する。テスト実行が必要な場合に使用。
tools: Bash, Read, Grep, Glob
model: haiku
permissionMode: bypassPermissions
---

テストスイートを実行し、結果を分析してください。

実行手順:
1. プロジェクトのテストフレームワークを特定する
2. テストスイートを実行する
3. 失敗テストのみを抽出する

報告フォーマット:
- 全テスト数 / 成功数 / 失敗数
- 失敗テストごとに: テスト名、エラーメッセージ、該当ファイルと行番号
- 失敗の原因分析（可能な場合）

成功したテストの詳細は報告不要です。

Haikuモデルを使うことで、テスト結果の解析コストを抑えています。

PR作成アシスタント

コミット履歴を分析して、Pull Requestのタイトル・本文・レビューポイントを自動生成するサブエージェントです。

---
name: pr-creator
description: Pull Requestを作成する。PR作成やコミットまとめが必要な場合に使用。
tools: Bash, Read, Grep, Glob
model: sonnet
---

Pull Requestを作成してください。

手順:
1. git diffとgit logで変更内容を把握する
2. 変更の目的と影響範囲を分析する
3. Conventional Commit形式でPRタイトルを生成する
4. 変更概要・テスト方針を含むPR本文を作成する
5. gh pr createで実際にPRを作成する

PRタイトルは70文字以内に収めてください。
本文にはレビュアーへの注意点を含めてください。

データベースクエリ検証（hooks連携）

PreToolUse hooksを使い、Bashコマンドの実行前にSQLの書き込み操作を自動でブロックする例です。

---
name: db-reader
description: 読み取り専用のデータベースクエリを実行する。データ分析やレポート生成に使用。
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

データベースアナリストとして、SELECTクエリのみでデータを分析してください。
INSERT、UPDATE、DELETE等の書き込み操作は実行できません。

対応する検証スクリプト（./scripts/validate-readonly-query.sh）:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "ブロック: 書き込み操作は許可されていません。SELECTクエリのみ使用してください。" >&2
  exit 2
fi
exit 0

hooksの終了コード2はツール実行をブロックし、stderrのメッセージをClaude に返します。

並列実行とバックグラウンド処理

サブエージェントはフォアグラウンド（完了まで待機）とバックグラウンド（並行実行）のどちらでも動作します。

フォアグラウンド実行

メイン会話をブロックし、権限プロンプトや追加質問をユーザーに転送します。確実な制御が必要な場合に適しています。

バックグラウンド実行

作業を続けながら並行してサブエージェントを動かせます。起動前に必要なツール権限がまとめてプロンプトされ、実行中は事前承認された権限で自律的に動作します。

認証モジュール、データベース層、APIモジュールを別々のサブエージェントで並列に調査して

このように指示すると、3つのExploreサブエージェントが同時に起動し、それぞれ独立してコードベースを調査します。

バックグラウンド実行時の制約:

• MCPツールは利用不可
• 追加の権限確認が必要な操作は自動拒否される
• AskUserQuestionなどのユーザー対話ツールは失敗する（ただしサブエージェント自体は継続）

実行中のタスクをバックグラウンドに切り替えるには Ctrl+B を押します。

サブエージェントとSkillsの違い

Claude Codeにはサブエージェントに似た機能としてSkillsがあります。両者は目的が異なるため、使い分けが重要です。

判断の目安:

• テスト実行やログ解析など「大量の出力をメインコンテキストに持ち込みたくない」場合 → サブエージェント
• コーディング規約やデプロイ手順など「メインの会話に知識を追加したい」場合 → Skills
• 両方の性質がある場合 → Skillsにcontext: forkを指定してサブエージェントとして実行

両者は併用も可能です。サブエージェントのskillsフィールドにSkills名を指定すると、スタートアップ時にスキルの全コンテンツがサブエージェントに注入されます。

---
name: api-developer
description: APIエンドポイントをチーム規約に従って実装する
skills:
  - api-conventions
  - error-handling-patterns
---

永続メモリによるサブエージェントの成長

memoryフィールドを設定すると、サブエージェントに会話を跨いで知識を蓄積するディレクトリが割り当てられます。

メモリが有効な場合、MEMORY.mdの先頭200行がシステムプロンプトに自動注入されます。コードレビュアーであれば、過去に発見したパターンや頻出する問題をメモリに蓄積し、次回以降のレビュー品質を向上させられます。

---
name: code-reviewer
description: コード品質とセキュリティを重視したレビューを実施する
tools: Read, Grep, Glob, Bash
memory: project
---

コードレビューを実施してください。
レビュー中に発見したコードベースのパターン、規約、
頻出する問題をメモリに記録してください。

モデル選択によるコスト最適化

サブエージェントのモデル選択は、品質・速度・コストのトレードオフです。

読み取り専用の探索タスクにはhaikuを、判断力が求められるレビュー系タスクにはsonnetを指定するのが実用的な使い分けです。

よくある失敗と対処法

サブエージェントが自動的に呼び出されない

descriptionの記述が曖昧だと、Claudeがタスクとの関連性を判断できません。「Use proactively when…」のように、いつ使うべきかを明示してください。

# NG: 曖昧な説明
description: コードをレビューする

# OK: 具体的なトリガー条件を記述
description: コード変更後にセキュリティと品質をレビューする。コード変更があった場合に自動的に使用する。

コンテキストの断裂による品質低下

サブエージェントはメイン会話の履歴を引き継ぎません。ファイル書き込み系のタスクを委任する場合は、必要なコンテキスト（対象ファイルパス、変更方針、関連仕様）をすべてプロンプトに含めるか、ファイル経由で渡す設計にしてください。

サブエージェント数の増加によるトークン消費

起動時にすべてのサブエージェントのnameとdescriptionがコンテキストに読み込まれます。大量に登録するとトークンを消費し、メイン会話の品質に影響します。実際に使用するサブエージェントだけを有効にしてください。

バックグラウンド実行時の権限不足

バックグラウンドサブエージェントは起動時に権限をまとめて取得します。実行中に追加の権限が必要になった場合は自動拒否されるため、必要な権限は起動前に確保されるよう設定してください。問題が発生した場合は、サブエージェントを再開（resume）してフォアグラウンドで再試行できます。

CLIフラグによる一時的なサブエージェント定義

自動化スクリプトやCI/CDパイプラインでは、--agentsフラグでセッション限定のサブエージェントを定義できます。ディスクに保存されないため、テストや一時的な用途に適しています。

claude --agents '{
  "lint-checker": {
    "description": "リントエラーを検出して修正提案を返す",
    "prompt": "リントエラーを分析し、修正方法を提案してください。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "haiku"
  }
}'

特定のサブエージェントを無効化する方法

settings.jsonのdeny配列に追加することで、特定のサブエージェントの使用を禁止できます。

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(my-custom-agent)"]
  }
}

CLIフラグでも指定可能です。

claude --disallowedTools "Task(Explore)"

まとめ

Claude Codeのサブエージェントは、コンテキストウィンドウの効率的な管理と専門タスクの委任を実現する機能です。

効果的に運用するための要点は以下のとおりです。

• descriptionを具体的に書く: Claudeの自動委任精度はdescriptionの品質に直結する
• 読み取り系タスクから始める: コードベース探索やテスト結果解析など、メインコンテキストの汚染防止効果が大きいタスクが最適
• 書き込み系タスクは慎重に設計する: 必要なコンテキストを明示的に渡す仕組みを作る
• モデル選択でコストを制御する: 探索にはHaiku、レビューにはSonnetなど使い分ける
• Skillsとの併用を検討する: 規約や知識はSkillsで注入し、実行はサブエージェントに委任する構成が強力

公式ドキュメント（カスタムサブエージェントの作成 - Claude Code Docs）も併せて参照してください。