はじめに
「Claude Codeを使っていると、だんだんコンテキストが汚れていく」
ある処理の試行錯誤が積み重なり、メインのやり取りに不要な情報が混入し、最終的に推論の精度が落ちてしまう。この問題を根本的に解決するのがSubagent（サブエージェント）です。
Subagentは独立したコンテキストウィンドウで動作する専門エージェントです。メインセッションを汚さずに特定のタスクを処理し、結果だけを返してくれます。2025年後半からコミュニティでの活用が急速に広まり、GitHubには100件以上の専門Subagentを集めたリポジトリが複数登場するほど注目されています。
この記事では、Subagentの基本的な作り方から実践的なベストプラクティスまで、2026年時点の最新情報を網羅します。
Subagentとは何か
Claude CodeのSubagentは、専門的なAIアシスタントとして動作します。
- 独立したコンテキストウィンドウ
メインセッションとは別のコンテキストで動作 - カスタムシステムプロンプト
タスクに特化した役割定義 - 制限されたツールアクセス
必要最小限のツールのみ使用可能
なぜSubagentを使うのか
| 利点 | 説明 |
|---|---|
| コンテキスト保護 | 試行錯誤の過程がメインセッションに残らない |
| 精度向上 | 専門化されたプロンプトで特定タスクの品質が上がる |
| コスト管理 | 単純なタスクは安価なモデル（Haiku）に振れる |
| 並列実行 | 複数のSubagentを同時に走らせられる |
| 再利用 | 一度作れば何度でも使える |
基本的なファイル構造
SubagentはYAMLフロントマター付きのMarkdownファイルとして定義します。
---
name: code-reviewer
description: Proactively reviews code for quality, security, and maintainability. Use when reviewing PRs or checking code before commit.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: dontAsk
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- No exposed secrets or API keys
- Proper error handling
- Good test coverage
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
フロントマター全フィールド解説
name（必須）
エージェントの識別子。@name 記法での明示的呼び出しにも使われます。
name: code-reviewer
- ケバブケース（小文字+ハイフン）で記述
- 短く、役割が伝わる名前にする
description（必須・最重要）
このフィールドが自動委任の精度を決定します。
Claude Codeはdescriptionを読んで、そのSubagentにタスクを委任するかどうかを判断します。
# 悪い例
description: Code reviewer
# 良い例
description: Proactively reviews code for quality, security, and maintainability.
Use when reviewing PRs, checking code before commit, or analyzing changed files.
自動委任を強制させたい場合
特定のタスクが来たら必ずSubagentに委任させたい場合は、MUST BE USED や use proactively を入れます。
description: Debugging specialist for errors, test failures, and unexpected behavior.
MUST BE USED when encountering any errors or test failures.
CLAUDE.mdとの連携
descriptionだけでなく、CLAUDE.md側にも委任方針を書くことで安定性が増します。
## コーディング規約
- 機能実装に集中し、i18n処理はすべて ui-text-translator に委任する
- 実装後に必ず code-reviewer を呼び出してレビューを受けること
tools（最小権限の原則）
Subagentが使用できるツールを明示的に制限します。これはセキュリティと予測可能性の両方に効きます。
| ユースケース | 推奨ツールセット |
|---|---|
| 探索・分析のみ | Read, Grep, Glob |
| 分析＋コマンド実行 | Read, Grep, Glob, Bash |
| コード実装 | Read, Write, Edit, Bash, Grep, Glob |
| リサーチ | Read, Grep, Glob, WebFetch, WebSearch |
不要なツールを与えると、予期しない副作用が発生するリスクが上がります。
model（コスト最適化）
| モデル | 用途 |
|---|---|
haiku |
探索・分析・読み取り専用タスク |
sonnet |
実装・複雑な推論が必要なタスク |
opus |
非常に複雑な設計・判断が必要なタスク |
inherit |
親セッションと同じモデルを使う |
メインセッションをOpusで動かしながら、Subagentの定型タスクをSonnetやHaikuで処理するとコストを大幅に削減できます。
permissionMode（権限制御）
| モード | 動作 | 用途 |
|---|---|---|
default |
確認プロンプトあり | 通常の対話的作業 |
acceptEdits |
ファイル編集を自動承認 | バッチ修正・自動化 |
dontAsk |
権限プロンプトを自動拒否 | 読み取り専用分析 |
bypassPermissions |
全チェックをスキップ | 信頼済みパイプラインのみ |
plan |
読み取り専用の計画フェーズ | 設計・計画フェーズ |
注意点として、親セッションが bypassPermissions の場合は子のSubagentでもオーバーライドできません。
memory
セッションをまたいで知識を蓄積できる新しいフィールドです。
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob, Bash
model: sonnet
memory: user
---
メモリのスコープ
| スコープ | 保存場所 | 用途 |
|---|---|---|
user |
~/.claude/agent-memory/<agent-name>/ |
全プロジェクト共通の個人知識 |
project |
.claude/agent-memory/<agent-name>/ |
チーム共有の知識（git管理可能） |
起動時にMEMORY.mdの最初の200行がシステムプロンプトに注入されます。コードベースのパターン、設計判断、アーキテクチャの知識を蓄積することで、Subagentが回を重ねるごとに賢くなります。
hooks（上級）
フロントマター内でhooksを定義することで、エージェント定義とフック設定を1ファイルに集約できます。
---
name: safe-bash-runner
description: Runs bash commands safely with validation
tools: Bash, Read
model: haiku
hooks:
PreToolUse:
- matcher: Bash
command: "./validate-command.sh"
---
skills（知識の注入）
Subagentに特定の専門知識を事前に読み込ませることができます。
---
name: api-developer
description: Implements API endpoints following team conventions.
tools: Read, Write, Edit, Bash
model: sonnet
memory: project
skills:
- api-conventions
- error-handling-patterns
---
skills: に列挙したSkillsのコンテンツが、起動時にSubagentのコンテキストに注入されます。Subagentが発見する必要がなく、最初から専門知識を持った状態でタスクを開始できます。
システムプロンプト本文の書き方
セクション構成
LayerXチームの実践や公式ドキュメントから導き出された効果的な構成です。
## Role
You are a senior [専門領域] specialist.
## When Invoked
1. 最初に行う具体的なアクション
2. 次のアクション
3. ...
## Key Practices
- 守るべき方針
- 重要な制約
## Important Notes
- 避けるべき行動
- エッジケースの処理
## Example Usages
[入力例と期待される出力例]
過度な詳細化を避ける
長いプロンプトが良いわけではありません。必要最小限の情報のみを記述します。過度な詳細化は以下の問題を引き起こします。
- コンテキストの無駄遣い
- 柔軟性の低下
- メンテナンスコストの増加
実践テンプレート集
コードレビュアー（読み取り専用）
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality,
security, and maintainability. Use when reviewing PRs or before committing.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: dontAsk
---
You are a senior code reviewer.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
Provide feedback by priority:
- Critical (must fix)
- Warnings (should fix)
- Suggestions (consider)
デバッガー（修正あり）
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior.
MUST BE USED when encountering any errors or test failures.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify the solution works
For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
データ分析（コスト重視）
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights.
Use proactively for any data analysis tasks.
tools: Bash, Read, Write
model: haiku
---
You are a data scientist specializing in SQL and BigQuery analysis.
When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Analyze and summarize results
4. Present findings clearly
Key practices:
- Write optimized queries with proper filters
- Include comments explaining complex logic
- Format results for readability
記憶を持つコードレビュアー（memoryあり）
---
name: codebase-expert
description: Expert in this specific codebase. Builds knowledge over time.
Use proactively for architectural questions and code reviews.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---
You are a codebase expert who builds knowledge over time.
When invoked:
1. Check your memory for relevant context
2. Perform your analysis
3. Update your memory with new insights
Update memory with:
- Architectural patterns discovered
- Important file relationships
- Team conventions and decisions
- Common pitfalls found
配置場所とスコープ
Subagentは目的に応じて複数の場所に配置できます。
| 場所 | スコープ | 用途 |
|---|---|---|
.claude/agents/ |
プロジェクト | コードベース固有。git管理でチーム共有可能 |
~/.claude/agents/ |
ユーザー | 全プロジェクトで使える個人設定 |
--agents フラグ |
セッション限定 | テスト・自動化スクリプト向け |
| プラグイン経由 | プラグイン | コミュニティからのインストール |
優先順位はプロジェクト > ユーザー > プラグインの順です。同名のSubagentがある場合、より優先度の高い場所のものが使われます。
呼び出し方法
自動委任（暗黙的呼び出し）
descriptionに合致するタスクが来ると、Claude Codeが自動的に適切なSubagentに委任します。
ユーザー: このPRのコードをレビューして
Claude: (code-reviewerのdescriptionと一致するため自動委任)
課題として、自動委任は100%安定しません（LayerXチームでも課題として報告されています）。
明示的呼び出し
@agent-name 記法で確実に特定のSubagentを呼び出せます。
@code-reviewer このPRをレビューして
@debugger このエラーを調査して
重要なフローでは明示的呼び出しをフォールバックとして設計しておくことを推奨します。
実行パターン：並列 vs 逐次
並列実行（Parallel）
以下の条件が揃う場合に有効です。
- タスクが3つ以上ある
- 各タスクが独立している（依存関係なし）
- ファイルの競合がない
ユーザー: セキュリティ、パフォーマンス、コーディング規約の3観点でレビューして（use subagents）
Claude:
→ security-auditor: セキュリティ脆弱性スキャン
→ performance-analyzer: パフォーマンス分析
→ style-checker: コーディング規約チェック
↓ (並列実行後)
→ 結果を統合して報告
並列実行は、1エージェントで10分かかる調査を30秒に短縮できることがあります。ただし同時実行の上限はあるため、2〜4エージェントが最適だ。
逐次実行（Sequential）
以下の場合は逐次実行が適切です。
- タスク間に依存関係がある
- 共有ファイルや状態がある
- 前のSubagentの結果を次が使う
Spec-Writer → Architect → Implementer → Test-Runner
PubNubのチームはこのパターンで「プロダクト仕様 → アーキテクチャ設計 → 実装・テスト → PRの提出」という再現性のあるパイプラインを構築しています。
設計の4原則
1エージェント1責務
複数の役割を1つのエージェントに詰め込まない。責務が混在すると精度が下がり、デバッグも難しくなります。
# 悪い例: 1エージェントで何でもやろうとする
name: dev-assistant
description: Helps with code review, debugging, testing, and documentation
# 良い例: 責務を分割する
name: code-reviewer # レビュー専門
name: debugger # デバッグ専門
name: test-writer # テスト作成専門
name: doc-writer # ドキュメント作成専門
共通ルールはCLAUDE.mdへ
複数のSubagentで同じルールが必要な場合、各ファイルに重複して書かない。
# CLAUDE.md
## コーディング規約
- TypeScriptを使用する
- ESLintのルールに従う
- テストカバレッジ80%以上を維持する
このルールは全SubagentのコンテキストにCLAUDE.md経由で共有されます。
自動委任の限界を知る
自動委任は便利ですが、複雑なワークフローでは不安定になることがあります。重要なSubagentには @name による明示的呼び出しのパターンも設計に含めましょう。
モデルのコスト最適化
すべてのSubagentにSonnetやOpusを使う必要はありません。
探索・検索タスク → Haiku（速くて安い）
分析・実装タスク → Sonnet
複雑な設計・判断 → Opus
スキルとの使い分け
SubagentとSkillsの使い分けの基準は「コンテキストをどう扱うか」です。
| 観点 | Skills | Subagents |
|---|---|---|
| コンテキスト | 親と共有 | 独立 |
| 適したタスク | 文脈が重要な継続作業 | 試行錯誤を伴う調査・処理 |
| 結果の見え方 | プロセス全体が見える | 結果のみ受け取る |
| 呼び出し | 自然言語 |
@name 記法が使える |
| 典型例 | TDD、コミット作成 | エラー調査、ドキュメント検索 |
「このタスクの試行錯誤をメインセッションに残したくないか？」YesならSubagent。
チームへの展開
LayerXモバイルチームの「Subagents祭」事例から、チームへの展開方法を整理します。
個人活用に留まる問題
- どのSubagentを誰が作ったか不明
- チーム全体の生産性に繋がらない
- 担当者が変わると知識が失われる
展開のための5ステップ
- キックオフ: 既存Subagentを相互共有（用途・入出力・使いどころを共有）
- アイデア出し: 日常の開発プロセスから自動化できる箇所を列挙
- 担当決め: アウトカムベース（利用頻度・インパクト・担当者の知識）で絞り込み
- 1週間で作成: ハッカソン形式ではなく宿題形式で完成度を高める
- デモ&ディスカッション: 作成物と苦労した点を共有し、改善につなげる
.claude/agents/ に配置してgitコミットすることで、チーム全員が改善に参加できる共有資産になります。
コミュニティリソース
自分でゼロから作る前に、コミュニティのSubagentを参考にすることをおすすめします。
- VoltAgent/awesome-claude-code-subagents: 100件以上の専門Subagentを収録
- 0xfurai/claude-code-subagents: 100件以上のプロダクション向けSubagent
- hesreallyhim/awesome-claude-code: Skills・Hooks・スラッシュコマンドも含む総合コレクション
また、/agents コマンドを使えば自然言語でSubagentを簡単に作成できます。
まとめ
Subagent作成のポイントを一行でまとめると
「descriptionで委任精度を決め、toolsで最小権限を守り、1エージェント1責務で設計する」
各フィールドの役割を理解した上で設計すれば、メインセッションを汚さずに専門化されたタスクを高品質に自動処理できます。ぜひ自分のワークフローに合ったSubagentを作ってみてください。
参考資料
- Create custom subagents - Claude Code Docs
- Best practices for Claude Code subagents - PubNub
- Best Practices with Claude Code Subagents Part II - PubNub
- Claude Code Sub-Agents: Parallel vs Sequential Patterns - claudefa.st
- Claude Code Deep Dive - Subagents in Action - Medium
- 7 powerful Claude Code subagents you can build in 2025 - eesel.ai
- VoltAgent/awesome-claude-code-subagents - GitHub
- 属人化からチームの共有知へ ~LayerXモバイルチームの「Claude Code Subagents祭」開催レポート~