Claude Code カスタムサブエージェント実践ガイド — AGENT.mdで専門特化AIチームを構築する

Claude Codeで「この調査、サブエージェントに任せたい」「コードレビューだけ安いモデルで回したい」と思ったことはありませんか？ .claude/agents/ にAGENT.mdファイルを1つ置くだけで、ツール制限・モデル選択・専門プロンプトを備えたカスタムサブエージェントが作れます。本記事では、YAMLフロントマターの全設定項目から用途別の設計パターン、コスト最適化テクニック、既存のAgent Teams・Skills・Agent SDKとの使い分けまで、実装例付きで体系的に解説します。

AGENT.mdとは？ — カスタムサブエージェントの仕組み

サブエージェントが解決する課題

Claude Codeで複雑なタスクに取り組んでいると、メインの会話コンテキストがすぐに膨らんでいきます。テストの実行結果、ログの解析、ドキュメントの調査——これらの「重いが独立した作業」をメインコンテキストで行うと、本来集中すべき実装作業の精度が落ちてしまいます。

サブエージェントは、この問題をコンテキスト分離で解決します。各サブエージェントは独立したコンテキストウィンドウで動作し、専用のシステムプロンプト・ツールアクセス・パーミッションを持ちます。メインのClaude Codeがタスクの内容とサブエージェントの description を照合し、適切なサブエージェントに自動的に委譲してくれます。

Claude Codeにはビルトインのサブエージェントとして、コードベース探索用の Explore（Haikuモデル、読み取り専用）、プランモード用の Plan、複雑なマルチステップ作業用の General-purpose が用意されています。カスタムサブエージェントは、これらの仕組みをプロジェクト固有のニーズに合わせて拡張するものです。

配置場所とスコープ（プロジェクト vs ユーザーレベル）

AGENT.mdの配置場所によってスコープと優先度が決まります。

優先度: 高 → 低

1. --agents CLIフラグ   … セッション限定（ディスクに保存されない）
2. .claude/agents/      … プロジェクトスコープ（git管理してチーム共有可能）
3. ~/.claude/agents/    … ユーザースコープ（全プロジェクトで利用可能）
4. Plugin agents/       … プラグイン経由で提供

同名のサブエージェントが複数存在する場合、より優先度の高い場所のものが使われます。プロジェクト固有のエージェントは .claude/agents/ に、個人で全プロジェクトに使いたいエージェントは ~/.claude/agents/ に配置するのが基本です。

AGENT.mdの書き方 — YAMLフロントマターと本文の構成

YAMLフロントマター全設定項目リファレンス

AGENT.mdは、YAMLフロントマター（--- で囲む）＋ Markdown本文というシンプルな構成です。最小構成は name と description の2項目だけです。

---
name: code-reviewer
description: コードの品質・セキュリティ・保守性をレビューする。コード変更後に積極的に使用する。
tools: Read, Grep, Glob
model: sonnet
---

あなたはシニアコードレビュアーです。
呼び出されたら、対象コードを分析し、品質・セキュリティ・ベストプラクティスの観点から
具体的で実行可能なフィードバックを提供してください。

出力フォーマット:
- **Critical（必須修正）**: セキュリティ問題、バグ
- **Warning（推奨修正）**: パフォーマンス、可読性
- **Suggestion（検討）**: リファクタリング案

全フィールドの一覧は以下の通りです。

本文（システムプロンプト）の書き方のコツ

本文はそのままサブエージェントのシステムプロンプトになります。重要なのは、サブエージェントにはClaude Code本体のシステムプロンプトが渡されない点です（基本的な環境情報のみ）。そのため、期待する振る舞いを本文に明示的に書く必要があります。

効果的な本文のポイントは3つです。

1. 役割の明示: 「あなたは〇〇の専門家です」で始める
2. 手順の明示: 番号付きリストでワークフローを定義する
3. 出力フォーマットの指定: どんな形式で結果を返すかを具体的に指示する

用途別 設計パターン5選

1. Read-Only分析エージェント（コードレビュー・アーキテクチャ分析）

ファイルの読み取りと検索のみに制限し、コードを一切変更できない安全なエージェントです。

---
name: architecture-analyzer
description: プロジェクトのアーキテクチャを分析し、依存関係や設計上の問題点を報告する。コードベースの全体像を把握したいときに使用する。
tools: Read, Grep, Glob
model: haiku
---

あなたはソフトウェアアーキテクトです。コードベースを分析し、以下の観点でレポートを作成してください。

分析項目:
1. ディレクトリ構造とモジュール分割
2. 依存関係の方向（循環依存の有無）
3. レイヤー違反（UIからDBへの直接アクセス等）
4. 設計パターンの一貫性

出力は Markdown 形式で、問題の深刻度を Critical / Warning / Info で分類すること。

2. WebSearch調査エージェント（技術リサーチ・競合調査）

Web検索に特化させることで、調査結果の大量のテキストがメインコンテキストを圧迫するのを防ぎます。

---
name: tech-researcher
description: 技術的な調査・競合分析・ライブラリ選定の情報収集を行う。最新の技術動向やベストプラクティスを調べたいときに使用する。
tools: WebSearch, WebFetch, Read
model: sonnet
---

あなたは技術リサーチャーです。与えられたテーマについてWeb検索を活用して調査し、
簡潔なレポートにまとめてください。

調査フロー:
1. テーマに関連するキーワードで複数回検索
2. 信頼性の高いソース（公式ドキュメント、技術ブログ）を優先
3. 複数の情報源を突き合わせて正確性を担保

レポートフォーマット:
- **要約**: 3行以内
- **詳細**: 主要な発見事項
- **ソース**: 参照したURLリスト
- **推奨アクション**: 次に何をすべきか

3. コード生成エージェント（テスト生成・ボイラープレート作成）

Write、Edit、Bashを含めることで、実際にファイルを作成・編集できる実装力を持たせます。

---
name: test-generator
description: 既存コードに対するユニットテスト・統合テストを自動生成する。テストカバレッジを上げたいときに使用する。
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---

あなたはテストエンジニアです。指定されたソースコードを読み、
包括的なテストを生成してください。

手順:
1. 対象ファイルを読んで関数・クラスの仕様を把握
2. 既存のテストファイルがあればパターンを踏襲
3. テストを作成（正常系・異常系・エッジケース）
4. テストを実行して全件パスすることを確認

テスト方針:
- プロジェクト既存のテストフレームワークを使用
- モック・スタブは最小限に
- テスト名は「何をテストしているか」が分かる命名

4. ドキュメント生成エージェント（README・API仕様書）

---
name: doc-writer
description: README、API仕様書、アーキテクチャドキュメントを生成・更新する。ドキュメントの作成や更新が必要なときに使用する。
tools: Read, Write, Edit, Glob, Grep, WebFetch, WebSearch
model: sonnet
---

あなたはテクニカルライターです。コードを読み、正確で分かりやすいドキュメントを生成してください。

ドキュメント生成ルール:
- コードの実装から仕様を正確に読み取る（推測で書かない）
- 使用例（コードスニペット）を必ず含める
- 既存のドキュメントスタイルがあれば踏襲する

5. セキュリティ監査エージェント（依存関係・脆弱性チェック）

---
name: security-auditor
description: 依存関係の脆弱性、コード中のセキュリティ問題、秘密情報の漏洩をチェックする。セキュリティレビューやリリース前チェックに使用する。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたはセキュリティエンジニアです。以下の観点でプロジェクトを監査してください。

チェック項目:
1. `npm audit` / `pip-audit` による既知の脆弱性検出
2. ハードコードされたAPI キー・パスワード・トークンの検索
3. SQLインジェクション、XSS、コマンドインジェクションのパターン検出
4. 不適切なファイルパーミッション
5. .env ファイルが .gitignore に含まれているか

出力: 深刻度（Critical/High/Medium/Low）別に分類し、修正方法を提示

awesome-claude-code-subagents リポジトリには、上記のようなパターンが100種類以上収録されています。インストールスクリプトで必要なものだけ選んで .claude/agents/ に配置できるので、ゼロから書く前に一度覗いてみることをおすすめします。

モデルルーティングでコストを最適化する

タスク特性に応じたモデル選択の判断基準

model フィールドでサブエージェントごとに使用するモデルを指定できます。正直、この機能だけでもカスタムサブエージェントを作る価値があると感じています。

判断基準はシンプルです。

Haiku/Sonnet/Opusの使い分け実例

同一プロジェクトで3モデルを使い分ける構成例です。

.claude/agents/
├── quick-search.md      # model: haiku  — ファイル検索・定義ジャンプ
├── code-reviewer.md     # model: sonnet — コードレビュー・改善提案
└── complex-refactor.md  # model: opus   — 大規模リファクタリング

model を省略した場合は inherit（メイン会話と同じモデル）がデフォルトです。ビルトインの Explore サブエージェントが Haiku を使っているのは、まさにこの最適化の好例です。コードベースの探索は高速・低コストなモデルで十分だという設計判断が反映されています。

Agent Teams・Skills（SKILL.md）・Agent SDKとの使い分け

Claude Codeにはサブエージェント以外にも複数のエージェント機構があります。それぞれの位置づけを整理します。

flowchart TD
    A[やりたいこと] --> B{プログラムから制御したい?}
    B -->|Yes| C[Agent SDK]
    B -->|No| D{複数セッションで並行作業?}
    D -->|Yes| E[Agent Teams]
    D -->|No| F{コンテキストを分離したい?}
    F -->|Yes| G[AGENT.md サブエージェント]
    F -->|No| H{定型操作を再利用したい?}
    H -->|Yes| I[SKILL.md]
    H -->|No| J[メイン会話でそのまま実行]

組み合わせも可能です。たとえば、AGENT.mdの skills フィールドにスキルを指定すれば、サブエージェントの起動時にスキルの内容がコンテキストに注入されます。

よくあるハマりポイントと対処法

サブエージェントが呼ばれない・意図しないエージェントが呼ばれる

最も多いのが description の書き方が曖昧なケースです。Claude Codeは description を見てルーティングを判断するため、「いつこのエージェントを使うべきか」を具体的に書く必要があります。

# 悪い例
description: コードを分析する

# 良い例
description: TypeScriptプロジェクトのコードレビューを行い、品質・セキュリティ・保守性の観点からフィードバックを提供する。コード変更後に積極的に使用する。

また、明示的にサブエージェントを指定して呼び出すことも可能です。code-reviewerサブエージェントを使って最近の変更をレビューして のように依頼すれば、確実にルーティングされます。

ツール制限の落とし穴

tools で必要なツールを漏らすとサブエージェントが途中でエラーになります。たとえば、ファイルを生成するエージェントで Write を許可して Edit を忘れると、既存ファイルの更新ができません。

覚えておきたいポイントをまとめます。

• tools を省略するとメイン会話の全ツールを継承する。制限したい場合のみ明示的に指定する
• サブエージェントは別のサブエージェントを起動できない。ネストが必要な場合はメイン会話からチェーン実行する
• CLAUDE.mdの指示はサブエージェントにも適用されるが、Claude Code本体のシステムプロンプトは渡されない
• .claude/agents/ はgitにコミットしてチーム共有するのが推奨。チーム全員が同じサブエージェント構成で作業できる
• サブエージェントはセッション開始時に読み込まれるため、手動でファイルを追加した場合はセッション再起動か /agents コマンドで再読み込みが必要

AGENT.mdによるカスタムサブエージェントは、Claude Codeの日常的な開発フローを大きく効率化する仕組みです。ツール制限で安全性を確保し、モデル選択でコストを最適化し、専門プロンプトで出力品質を安定させる——この3つの軸を意識して設計すれば、あなたのプロジェクトに最適なAIチームを構築できます。まずは本記事のRead-Only分析エージェントをコピペして .claude/agents/ に配置するところから試してみてください。効果を実感したら、プロジェクト固有のエージェントを少しずつ増やしていくのがおすすめです。