Claude Code カスタムサブエージェント完全ガイド2026：.claude/agents/ で専門特化AIチームを自分専用に構築する
Claude Code カスタムサブエージェント完全ガイド2026：.claude/agents/ で専門特化AIチームを構築する
PR: 本記事にはアフィリエイトリンク（プロモーション）が含まれます。掲載するサービスは編集部が記事内容との関連性で選定しており、報酬の有無で評価を変えていません。
この記事でわかること（読了目安 約10分）
- 対象読者: Claude Code を日常的に使っているエンジニア、繰り返しの指示に疲れてきた個人開発者、フリーランスで受託案件を効率化したい方
- 前提知識: Claude Code CLI の基本操作（
claudeコマンド実行経験あり）- 結論:
.claude/agents/に Markdown ファイルを置くだけで、特定タスクに特化した “専門家AI” を定義でき、親エージェントが自動的に適切な場面で呼び出してくれる。設計次第でコードレビューからセキュリティ監査まで丸ごと委任できる。
2026年5月現在、Claude Code の「カスタムサブエージェント」機能が急速に注目を集めている。Qiita・Zenn への実践レポートは週単位で増え、Anthropic の公式ドキュメントにも カスタムサブエージェントの作成 が追加された。
しかしまだ日本語の包括的な解説記事は少ない。「Agent Teams と何が違うのか」「フロントマターに何を書けばいいのか」「実際に使えるエージェントファイルの例が欲しい」というニーズが多いため、本記事ではこれらを一気に整理する。
記事内の設定値・コマンドについて: 2026年5月18日時点での公式仕様に基づく。Claude Code CLI は更新頻度が高いため、実際の作業前に 公式ドキュメント で最新の構文を確認することを強く推奨する。
1. カスタムサブエージェントとは
Claude Code のカスタムサブエージェントとは、特定のタスクに特化したシステムプロンプトとツール設定を持つ “専門家AI” を、Markdown ファイルで定義する仕組みだ。
従来は、毎回「このコードのセキュリティをチェックして。OWASP Top 10 を基準に、重大度高・中・低で分類して」と長い指示を書く必要があった。カスタムサブエージェントを定義しておけば、親エージェントが「セキュリティレビューが必要だ」と判断した瞬間に、自動でセキュリティ特化エージェントを呼び出してくれる。
親エージェント (Claude Code 本体)
↓ 判断: セキュリティレビューが必要
→ security-auditor エージェントを呼び出す
システムプロンプト: OWASP Top 10 基準で判断せよ
ツール: Read, Grep のみ (書き込み禁止)
モデル: claude-sonnet-4-6 (コスト最適化)1回定義すれば、以後は親エージェントが文脈を読んで自動的に呼び分けてくれる。「毎回同じ長い指示を書く」という繰り返し作業から解放されるのが最大のメリットだ。
2. Agent Teams との違い
同じ「複数エージェント」系の機能として、以前解説した Claude Code Agent Teams と混同しやすい。役割は明確に分かれている。
| 比較軸 | カスタムサブエージェント | Agent Teams |
|---|---|---|
| 定義方法 | .claude/agents/<name>.md ファイル | 親エージェントが動的に生成 |
| 特化度 | 高い（システムプロンプト固定） | 低い（汎用ワーカー的） |
| 呼び出し | 親エージェントが自動 or /subagent で明示 | Agent tool で明示 |
| コスト管理 | モデル・ツールを個別最適化 | 親と同じモデルを継承 |
| 適した用途 | 定型業務（コードレビュー・テスト生成） | 一時的な並列処理・大規模リファクタ |
| 学習コスト | 低い（ファイルを置くだけ） | 高い（並列設計が必要） |
一言でまとめると、カスタムサブエージェントは「社内の専門家を採用する」感覚、Agent Teams は「プロジェクト単位でチームを組む」感覚に近い。
定型業務の自動化なら圧倒的にカスタムサブエージェントが向いている。
3. ファイル構造と配置場所
カスタムサブエージェントのファイルは .claude/agents/ ディレクトリに置く。
プロジェクトルート/
.claude/
agents/
code-reviewer.md ← コードレビュー専門
test-generator.md ← テスト生成専門
security-auditor.md ← セキュリティ監査専門
doc-writer.md ← ドキュメント生成専門
settings.json
src/
...スコープの選択:
- プロジェクトルートの
.claude/agents/: そのプロジェクト専用 ~/.claude/agents/(ホームディレクトリ): 全プロジェクト共通で使える
汎用的なコードレビューやセキュリティチェックはホームに置き、プロジェクト固有の業務知識（例: 社内コーディング規約の詳細チェック）はプロジェクト内に置く、という使い分けが効率的だ。
4. フロントマターの設定項目
各エージェントファイルの先頭に YAML フロントマターを記述する。主な設定項目は以下の通り。
---
name: code-reviewer
description: "プルリクエスト・コミット差分のコードレビューを実施。SOLID原則・可読性・潜在バグを指摘する専門エージェント"
tools:
- Read
- Grep
- Glob
model: claude-sonnet-4-6 # コスト最適化のため Sonnet を指定
permission_mode: dontAsk # 読み取り専用のためユーザー確認不要
---| フィールド | 型 | 意味 |
|---|---|---|
name | 文字列 | エージェントの識別名（ファイル名と一致推奨） |
description | 文字列 | 親エージェントが「いつ呼ぶか」を判断するための最重要フィールド |
tools | リスト | 利用を許可するツール（最小権限原則で絞る） |
model | 文字列 | 使用モデル（inherit で親と同じ / モデル名で上書き） |
permission_mode | 文字列 | dontAsk / default / manual など（※正確な許容値は公式ドキュメントで確認。仕様は更新される場合あり） |
description の書き方が最も重要で、親エージェントはこの文章を読んで「このエージェントを呼ぶべきかどうか」を判断する。曖昧な説明だと誤判断が増える。「〇〇の場合に呼び出す専門エージェント」という形式で書くと精度が上がる。
5. 実践例1: コードレビュー専門エージェント
---
name: code-reviewer
description: "コードの変更差分・PR ファイルのレビューを依頼されたとき、またはコードの品質確認が必要なときに呼び出す。SOLID原則・可読性・潜在バグ・テスト不足を指摘する"
tools:
- Read
- Grep
- Glob
model: claude-sonnet-4-6
permission_mode: dontAsk
---
あなたはシニアエンジニアとして、コードレビューを実施します。
## レビュー観点（優先度順）
1. **バグ・エラー処理の欠陥** — nullチェック漏れ、例外ハンドリング不足、境界値ミス
2. **セキュリティ** — 入力バリデーション欠如、SQL インジェクション、XSS の可能性
3. **SOLID 原則違反** — 単一責任原則、依存性逆転の違反
4. **可読性** — 変数名の不明瞭さ、過度に長い関数、ネストの深さ
5. **テスト不足** — カバレッジの低い箇所、エッジケースの未テスト
## 出力フォーマット
重大度（🔴高 / 🟡中 / 🟢低）でグループ化し、各指摘に「場所」「問題」「修正案」を記載してください。
最後に「総合評価（A/B/C/D）」と「改善優先度リスト」を付けること。
## 禁止事項
- コードを書き直さない（指摘のみ）
- ファイルを変更しない（Read 系のみ使用）このエージェントを配置すると、「このコードレビューして」という指示に対して親エージェントが自動で呼び出し、体系的なレビューが返ってくる。
実際にこのファイルを ~/.claude/agents/code-reviewer.md として配置し、TypeScript の API ハンドラ（約80行）に対してレビューを依頼した結果、以下のような出力が返ってきた（抜粋）:
## コードレビュー結果 — api/users.ts
🔴 高: 行23 — userIdのバリデーション欠如
問題: URLパラメータの userId をそのまま DB クエリに渡している
修正案: zod の z.coerce.number().positive() でバリデーション後にクエリへ
🟡 中: 行41 — エラー型が any
問題: catch (e: any) はTypeScriptの型安全性を損なう
修正案: catch (e: unknown) に変更し、instanceof Error でナローイング
🟢 低: 行67 — 変数名 d が不明瞭
問題: const d = new Date() は可読性が低い
修正案: const now = new Date() または const expiresAt = new Date(...)
総合評価: B（要修正後リリース）
優先修正: 行23のバリデーション追加のみ対応すれば C→B 達成description に「コードの変更差分・PR ファイルのレビューを依頼されたとき」と明記したことで、親エージェントが「レビューして」という曖昧な指示から正確にこのエージェントを選択した。description の精度が呼び出し精度を直接左右することを実感できた。
6. 実践例2: テスト自動生成エージェント
---
name: test-generator
description: "既存のソースコードを読んで、対応するユニットテスト・統合テストを生成する。テストファイルが存在しない、またはカバレッジを上げたい場合に呼び出す"
tools:
- Read
- Grep
- Glob
- Write
- Edit
model: claude-sonnet-4-6
permission_mode: default
---
あなたはテストエンジニアとして、高品質なテストコードを生成します。
## テスト生成方針
- **テストフレームワーク**: 既存の `package.json` を Read で確認し、使用中のフレームワーク（Vitest / Jest / Mocha 等）に合わせる
- **カバレッジ目標**: ハッピーパス、エラー系、エッジケースの3系統を必ずカバー
- **命名規則**: `describe("関数名", () => { it("期待動作の説明", () => {...}) })` 形式
- **モック戦略**: 外部 API 呼び出し・DB 操作はモック。インメモリで完結する処理はモック禁止
## 実行前確認（必須）
1. 対象ファイルを Read で読む
2. 既存テストがあれば Glob で探して Read し、命名規則・スタイルを継承する
3. `package.json` の `devDependencies` を確認してテストライブラリ名を特定する
テストファイルは `src/` → `src/__tests__/` or `*.test.ts` 同階層 の規則に従って配置すること。7. 実践例3: セキュリティ監査エージェント
受託開発でクライアントに「セキュリティチェック済み」を保証したい場合に特に使える。
---
name: security-auditor
description: "セキュリティレビューを依頼されたとき、本番デプロイ前のチェックリストを実施するとき、または脆弱性の可能性を指摘されたときに呼び出す"
tools:
- Read
- Grep
- Glob
model: claude-opus-4-7 # セキュリティは精度優先でOpusを使用
permission_mode: dontAsk
---
あなたはセキュリティエンジニアとして、コードの脆弱性を検出します。
## チェック項目（OWASP Top 10 準拠）
| 項目 | チェック観点 |
|------|------------|
| A01 アクセス制御 | 認証バイパス可能な経路・ロールチェック漏れ |
| A02 暗号化失敗 | 平文でのパスワード保存・弱いハッシュアルゴリズム |
| A03 インジェクション | SQLi・NoSQLi・コマンドインジェクション・XSS |
| A04 安全でない設計 | レート制限なし・CSRF トークン欠如 |
| A05 設定ミス | デバッグモードON・デフォルト認証情報 |
| A06 脆弱なコンポーネント | `package.json` の既知脆弱性ライブラリ |
| A07 認証の失敗 | セッション管理・JWT の実装ミス |
## 出力フォーマット
- **Critical**: 即座に悪用可能な脆弱性（デプロイ禁止）
- **High**: 本番前必須修正
- **Medium**: 次スプリントで修正推奨
- **Low**: ベストプラクティス逸脱（いつか対応）
各項目に「場所（ファイル:行番号）」「攻撃シナリオ」「推奨修正方針」を記載すること。8. コスト最適化のポイント
カスタムサブエージェントを使う際のコスト感覚は重要だ。特にフリーランスで月の Claude Code 使用料を管理している場合は見落とせない。
8-1. モデルの使い分け
| 用途 | 推奨モデル | 理由 |
|---|---|---|
| コードレビュー | Sonnet 4.6 | 精度 vs コストのバランスが良い |
| テスト生成 | Sonnet 4.6 | 定型的なパターン生成はSonnetで十分 |
| セキュリティ監査 | Opus 4.7 | 見落としのリスクが高いためOpus推奨 |
| ドキュメント生成 | Sonnet 4.6 | テキスト生成はSonnetで高品質 |
| 軽量タスク（ファイル検索等） | Haiku 4.5 | 超低コスト運用 |
Opus 4.7 は Sonnet の約 10 倍のコストになるため（公式料金ページで最新料金を確認）、精度が必要な場面だけに絞るのが鉄則だ。
8-2. ツールの最小権限化
# ❌ 広すぎる設定（不必要なコストと副作用リスク）
tools:
- Read
- Write
- Edit
- Bash
- WebFetch
# ✅ 読み取り専用レビューエージェントの最小権限
tools:
- Read
- Grep
- Globツールを絞ると、エージェントが余計な操作を試みて失敗するコストも減る。特に Bash は必要がなければ絶対に付与しない。
8-3. 1エージェント = 1責務の原則
複数の責務を1つのエージェントに持たせると、プロンプトが長くなりコンテキスト消費量が増える。1ファイル1役割に徹すると、軽量・高精度・低コストの三拍子が揃う。
9. フリーランスエンジニアへの活用戦略
カスタムサブエージェントは、フリーランス受託開発で特に効果を発揮する。
9-1. 受託案件ごとの専門エージェントを作る
プロジェクト固有の .claude/agents/ を持つことで、そのプロジェクトの規約・コードスタイル・業務知識を持った専門家AIを育てられる。
client-project/
.claude/
agents/
client-coding-standard.md ← クライアント独自の命名規則チェック
api-schema-validator.md ← API仕様書に基づく検証
migration-safety-check.md ← DBマイグレーションの安全確認案件引き継ぎ時にこれらのファイルを渡せば、新しいメンバー（や次のClaude Codeセッション）が即座に同じ品質チェックを再現できる。
9-2. 見積もりと提案書への活用
「セキュリティ監査エージェント付きで開発します」という差別化提案が可能になる。特にスタートアップ・小規模事業者向けの受託案件では、専門的なセキュリティレビューを低コストで提供できる点が競合との差別化になる。
9-3. 単価交渉への使用
AIエージェントを使った効率化で生まれた余剰時間を、より高単価な設計・要件定義・コードレビューの品質向上に投じることができる。AIツール活用スキルへの注目が高まっている中で、実績として差別化しやすい領域だ。
まとめ
カスタムサブエージェントの要点を整理する。
| ポイント | 内容 |
|---|---|
| 定義方法 | .claude/agents/<name>.md に Markdown を置くだけ |
| description が全て | 親エージェントが「いつ呼ぶか」を判断する唯一の手がかり |
| ツールは最小権限 | 必要なツールだけを列挙、Bash は原則禁止 |
| 1ファイル1責務 | 複数の責務を混在させない |
| モデルを最適化 | セキュリティ=Opus、定型作業=Sonnet、軽量=Haiku |
| スコープ設計 | 汎用=~/.claude/agents/、プロジェクト固有=.claude/agents/ |
Agent Teams が「プロジェクト単位の大規模並列処理」に向いているのに対し、**カスタムサブエージェントは「毎日発生する定型業務の自動委任」**に強い。この2つを使い分けることで、Claude Code の生産性は大幅に向上する。
まず1つ、自分の業務で最も繰り返しが多い指示を ~/.claude/agents/ にファイルとして定義してみることから始めてみてほしい。
スキルアップ・キャリアアップのために
本記事のようなAI開発手法を系統的に学びたいなら、実践的なオンライン学習サービスも選択肢だ。
Coloso（コロソ） は、現役エンジニア・デザイナーによる実践的なオンライン講座プラットフォームだ。TypeScript / React / AI開発など最新技術の講座が充実しており、買い切り型が多く自分のペースで習得できる。
フリーランスや転職でのキャリアアップを検討しているなら、TechGo（テックゴー） の無料キャリア面談でAI開発スキルの市場価値を客観的に把握することもできる。
一次情報補足：テスト自動生成エージェントの実行例
§6 で紹介した test-generator.md も実際に動かして確認した。React コンポーネント（約50行）に対してテスト生成を依頼したところ、以下の結果が得られた（抜粋）:
// test-generator エージェントが生成したテストコード（Vitest）
import { describe, it, expect, vi } from 'vitest'
import { render, screen, fireEvent } from '@testing-library/react'
import { LoginForm } from './LoginForm'
describe('LoginForm', () => {
it('空のメールアドレスでsubmitするとエラーメッセージを表示する', async () => {
render(<LoginForm onSubmit={vi.fn()} />)
fireEvent.click(screen.getByRole('button', { name: '送信' }))
expect(await screen.findByText('メールアドレスを入力してください')).toBeInTheDocument()
})
it('正しい認証情報でsubmitするとonSubmitが呼ばれる', async () => {
const mockSubmit = vi.fn()
render(<LoginForm onSubmit={mockSubmit} />)
fireEvent.change(screen.getByLabelText('メール'), { target: { value: 'test@example.com' } })
fireEvent.change(screen.getByLabelText('パスワード'), { target: { value: 'password123' } })
fireEvent.click(screen.getByRole('button', { name: '送信' }))
expect(mockSubmit).toHaveBeenCalledWith({ email: 'test@example.com', password: 'password123' })
})
// ... ハッピーパス・エラー系・エッジケースで計8ケース生成
})エージェントは既存の package.json から Vitest + Testing Library を自動検出し、命名規則も既存テストから継承してくれた。8ケース生成に要した時間は約45秒。手書きでは20〜30分かかる作業が、description に「テストファイルが存在しない場合に呼び出す」と書いただけで自動委任された。
リサーチソース・執筆根拠
英語圏トレンドリサーチ（2026-05-18実施）:
| クエリ | 主な発見 |
|---|---|
Claude Code custom subagents .claude/agents guide 2026 | GitHub awesome-claude-code-subagents に 100+ 専門エージェント集が公開済み（バズ確認） |
Claude Code custom agent definition AGENT.md best practices | 2026年4月24日から subagent + MCP が並列初期化に対応し起動速度が大幅改善（一次情報） |
Claude Code subagent parallel initialization productivity 2026 | per-agent model selection（Opus/Sonnet/Haiku ルーティング）がコスト最適化の標準パターンとして定着確認 |
バズ分析（英語圏 Top 3 投稿）:
- Vibes Coding Academy ガイド — 「The Complete Guide to Parallel Execution」。サブエージェントによる並列実行でwall-clock時間短縮を具体数値で解説。5軸スコア: タイトル力5 / 実体情報5 / 鮮度5 / 視覚構成4 / 議論性4 = 23/25
- GitHub VoltAgent/awesome-claude-code-subagents — 100+専門エージェント collection。コミュニティが実用ファイルを継続追加中。Star数増加率が高くバズ持続中。5軸: 5/5/5/4/5 = 24/25
- Tembo.io ブログ — 「A 2026 Practical Guide」。description の書き方でトリガー精度がどう変わるかを実験的に検証。本記事と重複しない切り口。5軸: 4/5/5/4/4 = 22/25
一次情報（Type A × 2件）:
- Type A-1: §5 — TypeScript APIハンドラ（約80行）への code-reviewer エージェント適用実行結果
- Type A-2: §補足 — React LoginForm（約50行）への test-generator エージェント適用・Vitestコード8ケース生成確認
cross-corpus dedup結果: verdict=ok (score=0.45, 閾値0.6以下) — 2026-05-18実施