Claude Code Subagentsを使うと、コードベース調査、テスト設計、セキュリティレビュー、ドキュメント確認などを、メインの会話とは別のコンテキストを持つ専門エージェントへ分担できます。
Subagentは単なる長いプロンプトではありません。独自のシステム指示、利用できるツール、モデル、ターン数、権限を持ち、調査結果だけをメインエージェントへ返せます。大きなリポジトリで調査ログが増えすぎる問題や、レビュー観点が混ざる問題を抑えられます。
この記事では、プロジェクト内の.claude/agents/へSubagentを作成し、Webアプリの探索・テスト・セキュリティレビューを分担する設定、ツールを最小限にする方法、SkillsやHooksとの違いを解説します。
情報確認日：2026年7月11日（日本時間）
結論：調査・実装・検証の境界が明確な仕事だけをSubagentへ渡す
この記事の結論
- Subagentは別コンテキストで動く専門担当として使う
descriptionに「いつ呼ぶか」を具体的に書く- 読み取り専用の担当にはWrite・Editを渡さない
- 同じ責務のSubagentを増やしすぎず、出力形式を統一する
- 変更の最終判断、テスト結果、危険操作はメイン側で確認する
Claude Code Subagentsとは？
Subagentは、Claude Codeが必要に応じて呼び出す専門エージェントです。メインエージェントとは別のコンテキストウィンドウで作業するため、大量の検索結果やログをメイン会話へすべて持ち込まずに済みます。
Subagentごとに次を設定できます。
- 名前と、呼び出す条件を示す説明
- 専門分野を定めるシステムプロンプト
- 利用できるツール、利用できないツール
- 使用するモデル
- 最大ターン数
- 権限モード
- 読み込むSkills
- バックグラウンド実行に関する設定
組み込みSubagent
Claude Codeには、コードベースを素早く検索するExplore、実装前の計画に使うPlan、複数段階の一般作業を行うgeneral-purposeなどの組み込み担当があります。
まず組み込み担当で十分か確認し、組織固有のルール、定型の出力、限定したツール権限が必要な場合にカスタムSubagentを作ります。
Subagent・Skills・Hooksの違い
| 機能 | 役割 | 向いている例 |
|---|---|---|
| Subagent | 別コンテキストの専門担当 | コード調査、セキュリティレビュー、テスト分析 |
| Skill | 再利用する知識・手順・スクリプト | 社内APIの使い方、デプロイ手順、レビュー基準 |
| Hook | 特定イベントで必ず動かす処理 | 整形、Lint、危険コマンド拒否、監査ログ |
「セキュリティ観点で調べて要約する」はSubagent、「セキュリティ基準の資料」はSkill、「秘密ファイルへの書き込みを必ず止める」はHookに向いています。
Subagentを置く場所
プロジェクト単位
project/
└─ .claude/
└─ agents/
├─ architecture-explorer.md
├─ test-reviewer.md
└─ security-reviewer.md
プロジェクト固有のSubagentは.claude/agents/へ置き、Gitでレビューします。チーム全員へ同じ設定を配布できます。
ユーザー単位
~/.claude/agents/複数プロジェクトで個人的に使うSubagentを置きます。組織固有のルールを個人領域だけに置くと、チームメンバーと挙動が異なるため注意してください。
コードベース探索用Subagentを作る
まず、変更せずに構造だけを調べる担当を作ります。.claude/agents/architecture-explorer.mdを作成します。
---
name: architecture-explorer
description: Use when locating code, tracing data flow, or identifying affected files before implementation. Do not use for editing files.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 12
---
You are a read-only architecture explorer.
Your job:
1. Restate the investigation question.
2. Locate the entry points and relevant files.
3. Trace data flow across components, APIs, and storage.
4. Identify tests and configuration related to the change.
5. Report uncertainty and files you did not inspect.
Do not propose broad refactoring unless it is necessary to answer the question.
Do not edit files.
Return:
- Summary
- Data flow
- Relevant files with reasons
- Existing tests
- Risks and unknowns
descriptionは自動委譲の判断材料です。「詳しいエージェント」のような曖昧な説明ではなく、どの場面で呼ぶか、何をしないかまで書きます。
テストレビュー用Subagentを作る
次は、差分に対して不足しているテストを探す担当です。テスト実行だけ許可し、ソースコードの変更は行わせません。
---
name: test-reviewer
description: Use after an implementation plan or code change to find missing unit, integration, and E2E tests. Do not edit production code.
tools: Read, Glob, Grep, Bash
model: sonnet
maxTurns: 16
---
You review test coverage for a web application.
Rules:
- Read package.json before running commands.
- Run only existing test, typecheck, and lint scripts.
- Do not install packages.
- Do not change files.
- Do not use network commands.
- Separate confirmed failures from recommendations.
Return:
1. Changed behavior
2. Existing tests that cover it
3. Missing cases, ordered by risk
4. Commands executed and results
5. Minimal test files that should be added
Bashを許可すると、テスト以外のコマンドも提案できる可能性があります。Claude Codeの権限設定やHookも併用し、許可するコマンドを限定してください。
セキュリティレビュー用Subagentを作る
---
name: security-reviewer
description: Use when changes touch authentication, authorization, file upload, user input, external URLs, secrets, payments, or admin features.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 18
---
You are a read-only application security reviewer.
Review only evidence found in the repository.
Focus on:
- Authentication and session boundaries
- Authorization at server-side entry points
- Input validation and output encoding
- SSRF, path traversal, injection, and unsafe redirects
- Secret exposure and logging
- File upload validation
- Destructive operations and audit logs
For every finding include:
- Severity: critical, high, medium, low, or informational
- Evidence: file and relevant symbol
- Exploit scenario
- Concrete mitigation
- Confidence and missing context
Do not claim a vulnerability without repository evidence.
Do not edit files.
セキュリティ担当を自動で呼びたい場合は、descriptionに認証、ファイルアップロード、外部URLなどの具体的なトリガーを含めます。
Claude CodeからSubagentを呼び出す
自動委譲に任せるほか、プロンプト内で担当名を明示できます。
architecture-explorerを使って、
ログイン後にプロフィール画面へユーザー情報が届くまでの
データフローを調べてください。
まだファイルは変更しないでください。
関連API、認可処理、キャッシュ、既存テストを一覧にしてください。複数担当へ分ける場合は、結果を統合する基準も指定します。
次のPull Requestをレビューしてください。
1. architecture-explorerで影響範囲を確認
2. test-reviewerで不足テストを確認
3. 認証・入力処理に触れている場合だけsecurity-reviewerを使用
4. 最後に重複指摘をまとめ、重大度順の1つの一覧に統合
コード変更は行わないでください。Webアプリ開発での分担例
新機能を追加する前
- Explorerが関連ファイルとデータフローを調べる
- メインエージェントが実装計画を作る
- 利用者が計画と変更範囲を確認する
実装後
- Test reviewerが既存テストと不足ケースを調べる
- 必要な場合だけSecurity reviewerが権限境界を確認する
- メインエージェントが指摘を統合して修正する
- 正式なテストと差分を人間が確認する
障害調査
- ログ調査担当が事象と時間帯を整理する
- コード探索担当が該当経路を追う
- DB担当がクエリとロックを確認する
- メインエージェントが仮説を重複排除し、検証順を決める
出力形式を固定する
複数Subagentが自由形式で長文を返すと、統合が難しくなります。各担当に、見出し、重大度、証拠、未確認事項を固定して返させます。
## Finding
- Severity:
- Evidence:
- Confirmed behavior:
- Risk:
- Recommendation:
- Unknowns:同じ形式にすると、メインエージェントが重複した指摘をまとめやすく、Pull Requestのコメントにも転記しやすくなります。
ツール権限を最小限にする
探索担当
Read、Glob、Grepだけで十分なことが多く、WriteやEditは不要です。
テスト担当
Bashが必要でも、パッケージ追加、ネットワーク、デプロイ、DB変更を許可する必要はありません。権限設定やHookでコマンドを制限します。
実装担当
編集権限を渡す場合も、対象ディレクトリを明確にし、秘密ファイルや本番設定を変更しないルールを追加します。
プロンプトの「実行しないでください」だけを安全境界にしないでください。ツールを渡さない、サンドボックスで止める、承認を要求するという技術的な制限を併用します。
モデルを使い分ける
すべての担当へ最上位モデルを設定する必要はありません。単純なファイル探索は高速モデル、複雑な設計レビューは高性能モデルというように、品質と費用を分けられます。
- 短い検索・一覧化：高速なモデル
- 複数ファイルの因果関係：標準または高性能モデル
- 認証・複雑な障害分析：高性能モデル
- 大量のSubagent並列実行：利用量とレート制限を監視
利用できるモデル名と指定方法は更新されるため、Claude Codeの/agents画面や公式ドキュメントで確認してください。
Subagentを増やしすぎない
「React担当」「TypeScript担当」「フロント担当」のような近い担当を増やすと、どれを呼ぶか曖昧になります。責務は技術名より作業の境界で分けます。
| 分け方 | 評価 | 理由 |
|---|---|---|
| React担当・Vue担当 | プロジェクト次第 | 複数技術を同時に使わないなら分離効果が小さい |
| 探索・実装・テスト | 分けやすい | 権限と出力の目的が明確に異なる |
| セキュリティ・アクセシビリティ | 分けやすい | 専門的な評価基準と証拠形式を固定できる |
| 何でも担当 | 避ける | メインエージェントとの差がなくなる |
よくある失敗と対処方法
Subagentが呼ばれない
descriptionを具体化し、利用者の依頼に含まれる言葉と責務を合わせます。必要なら担当名を明示して呼びます。
同じ調査を複数担当が繰り返す
担当ごとの入力範囲を限定し、既に分かった事実と未解決事項を渡します。
回答が長く、統合できない
出力形式、最大件数、重大度、証拠ファイルを固定します。
想定外のコマンドを実行する
Bashを外すか、承認・Hook・サンドボックスで許可コマンドを限定します。
利用量が急増する
並列担当数、最大ターン、モデル、呼び出し条件を見直し、単純調査は組み込みExploreへ戻します。
あわせて読みたい記事
よくある質問
Subagentは自動で呼ばれますか？
descriptionと依頼内容をもとに自動委譲される場合があります。確実に使いたいときは、プロンプトでSubagent名を指定してください。
Subagent同士で直接会話しますか？
基本的にはメインエージェントが仕事を委譲し、結果を統合します。複雑な協調が必要ならAgent Teamsなど別の機能との違いを確認してください。
SubagentへSkillを読み込ませられますか？
設定でSkillsを指定できる場合があります。Skillの内容と権限を確認し、担当に必要なものだけを渡します。
Subagentはファイルを編集できますか？
WriteやEditなどのツールを許可すれば可能です。ただし、探索・レビュー担当は読み取り専用にした方が、責務と安全境界が明確になります。
何個まで作ればよいですか？
決まった数はありません。最初は探索、テスト、専門レビューの2〜3個から始め、繰り返し発生する責務だけを追加する方が管理しやすくなります。
まとめ
Claude Code Subagentsは、別コンテキストと限定ツールを持つ専門担当として、調査・テスト・レビューを分ける機能です。技術名ではなく、作業の目的、権限、出力形式が異なる単位で分けると効果が出ます。
最初は読み取り専用のExplorerとReviewerから始め、description、ツール、最大ターン、出力形式を明確にしてください。編集や外部操作を許可する場合は、Claude Codeの権限設定とHooksを使い、プロンプト以外の安全境界も設けます。