Claude Code サブエージェントの作り方と使いどころ：.claude/agents の frontmatter

2026年9月14日時点の公式 sub-agents ドキュメント(code.claude.com/docs/en/sub-agents)で確認した現行仕様を、初版(2026年4月)からの差分込みでまとめます。

• 置き場所と優先順位: 管理設定(組織) > --agents CLI フラグ(そのセッション) > .claude/agents/(プロジェクト) > ~/.claude/agents/(ユーザー) > プラグインの agents/。ディレクトリは再帰的に走査されるので agents/review/ のようなサブフォルダ分けができます。
• frontmatter: 必須は name(小文字とハイフン、: 不可)と description(いつ委譲するか。全エージェント合計で15,000トークンを超えると警告)。任意は tools(省略時は全ツール継承)、disallowedTools、model(sonnet / opus / haiku / fable / フルID / inherit)、permissionMode(default / acceptEdits / auto / dontAsk / bypassPermissions / plan)、skills、memory(user / project / local)、maxTurns、mcpServers、hooks、background、isolation: worktree、color、effort。
• /agents の変更: v2.1.198 以降ウィザードは開かず、「Create a personal code-improver subagent in ~/.claude/agents/」のように Claude に書かせます。両ディレクトリは監視されており、既存ファイルの編集は再起動なしで反映されます(新しい agents/ ディレクトリを初めて作ったときだけ再起動)。
• 組み込みサブエージェント: 読み取り専用の Explore(quick / medium / very thorough の深さ指定あり)、プランモード用の Plan、探索と変更の両方を行う general-purpose など。CLAUDE.md を読まない Explore / Plan は速い代わりにプロジェクト規約を知りません。
• 呼び方: 自然言語で名前を出すほか、@agent-code-reviewer の @メンションで確実に指定でき、claude --agent code-reviewer でセッション全体をそのエージェントとして起動できます。会話全体を引き継ぐフォークは /subtask(v2.1.212 以降)です。

初版で「tools: Read, Grep, Glob, Bash」と書いた設定例の書式は、現行仕様でもそのまま有効です。後半の設定例は変更していません。

サブエージェントで何が変わるか

通常のAIエージェント利用では、調査、実装、テスト、レビューが同じ会話に積み上がります。長いタスクではコンテキストが膨らみ、重要な情報が埋もれます。

サブエージェントを使うと、親エージェントは全体方針を持ち、子エージェントに限定タスクを渡せます。

親エージェント:
- 全体の目的
- 最終判断
- 統合

サブエージェント:
- 調査
- テスト
- レビュー
- ドキュメント整理

重要なのは、子に任せる作業を小さくし、親に返す情報の形式を先に決めることです。

効く場面1: 大量ファイルの探索

大規模リポジトリでは、親の会話で大量のファイルを読むとノイズが増えます。探索だけをサブエージェントに任せると、親の会話を軽く保てます。

Use the codebase-map subagent to investigate where authentication is handled.
Return only:
1. related files
2. current request flow
3. likely change points
4. risks
Do not edit files.

探索サブエージェントには、編集権限を持たせないのが基本です。

効く場面2: 独立した検証

実装後のテストやビルド確認は、独立タスクとして切り出しやすいです。

Use the test-runner subagent to run the relevant tests for this diff.
If tests fail, report the failure and likely cause.
Do not modify production code unless explicitly asked.

検証担当に修正まで任せると、実装担当の意図とずれることがあります。最初は「失敗原因の報告」までに絞る方が安全です。

効く場面3: レビュー

レビューはサブエージェントと相性がよい作業です。実装した本人とは別視点を作れるため、見落としを拾いやすくなります。

Use the code-reviewer subagent to review the current git diff.
Focus on:
- behavioral regressions
- missing tests
- security-sensitive changes
- unnecessary dependencies
Return findings by severity.

レビュー担当には、修正権限を与えず、指摘だけ返させる運用が扱いやすいです。

効く場面4: ニュース・仕様調査

AIツール系の記事や実装では、公式ドキュメントの確認が必要です。このような調査をサブエージェントに任せる場合は、出典URLと確認日を必ず返させます。

Use the research subagent to verify the latest official docs.
Return:
- official source URLs
- checked date
- what changed
- what is still uncertain
Do not rely on blog summaries.

使わない方がよい場面

サブエージェントは便利ですが、呼ぶだけでコストと時間が増えます。次のような作業では親エージェントだけで十分です。

• 1ファイル内の小さな修正
• タイポ修正
• 親の会話にある情報を細かく参照する作業
• 人間の判断待ちが多い作業
• 作業範囲がまだ定義できていない依頼

サブエージェント設定例

プロジェクト単位で使う場合、.claude/agents/code-reviewer.md のように置きます。

---
name: code-reviewer
description: Use after code changes to review correctness, security, and test coverage.
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer.

When invoked:
- Inspect the current git diff.
- Focus on bugs, regressions, missing tests, and security concerns.
- Do not rewrite files.
- Return findings ordered by severity.

ツール権限は最小にします。レビュー担当に Edit を持たせると、レビューのつもりが修正まで始めることがあります。

設計チェックリスト

• サブエージェントに任せる目的が1つに絞られている
• 子に渡す情報が自己完結している
• 返してほしい形式を指定している
• 不要な編集権限を与えていない
• 親エージェントが最終判断する前提になっている

次に読む

• 仕様駆動でAIエージェントに実装させる(依頼テンプレート・よくある失敗5つ)
• AGENTS.md完全ガイド
• Claude Code hooksレシピ7本(導入前に決める安全境界)

出典

• Subagents - Anthropic
• Claude Code settings - Anthropic