Claude Code のサブエージェント(.claude/agents)の作り方と使いどころ
Claude Code のサブエージェントを定義する方法を解説します。.claude/agents に置く Markdown の書き方、tools と model の指定、レビュー用・調査用エージェントの実例、メインのコンテキストを汚さない使い方を紹介します。
コードベース全体を調べさせると、Claude が読んだファイルの内容がすべてコンテキストに残り、その後の作業精度が落ちます。レビューを頼むと、レビュー観点の長い指示が本来のタスクと混ざります。
こうした問題を解決するのが サブエージェントです。サブエージェントは独立したコンテキストと専用の指示を持つ Claude で、メインの Claude が必要に応じて呼び出します。この記事では、定義ファイルの書き方と、効果が出やすい使い方を解説します。
KEY POINT
この記事で分かること
.claude/agents/に置く定義ファイルの書き方- tools・model の指定と、description による自動呼び出しの制御
- 調査用・レビュー用・テスト用の実例
サブエージェントの仕組み
メインの Claude がタスクを分解し、一部をサブエージェントに委任します。サブエージェントは自分のコンテキストで作業し、結果の要約だけをメインに返します。
| 項目 | メイン | サブエージェント |
|---|---|---|
| コンテキスト | 会話全体 | 委任された指示 + 自分が読んだ内容 |
| システムプロンプト | Claude Code 本体 + CLAUDE.md | 定義ファイルの本文 |
| 使えるツール | すべて(permissions に従う) | tools で限定可能 |
| モデル | セッションの設定 | model で個別指定可能 |
/agents コマンドで、定義済みのエージェント一覧の確認と、対話的な新規作成ができます。
定義ファイルの書き方
プロジェクト用は .claude/agents/<名前>.md、ユーザー全体用は ~/.claude/agents/<名前>.md に置きます。
---
name: code-reviewer
description: コード変更のレビューを行う。ユーザーがレビューを求めたとき、または実装が完了して差分が生まれたときに使う。
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
model: claude-opus-5
---
あなたはこのプロジェクトのシニアレビュアーです。`git diff` で変更内容を取得し、次の観点でレビューしてください。
1. CLAUDE.md の規約への適合
2. バグの可能性(境界値、null、例外処理)
3. セキュリティ(入力検証、秘密情報、インジェクション)
4. テストの有無と妥当性
出力は「重大 / 改善提案 / 軽微」に分類し、ファイル名と行番号を必ず添えてください。
コードの修正は行わず、指摘だけを返してください。| キー | 意味 |
|---|---|
name | エージェント名(英小文字とハイフン) |
description | いつ使うか。自動呼び出しの判断材料になるため具体的に書く |
tools | 使えるツールの一覧。省略するとメインと同じ |
model | 使用モデル。省略するとセッションと同じ |
用語解説
description の書き方: 「〜のときに使う」と条件を書くと自動呼び出しが安定します。逆に「ユーザーが明示的に依頼したときのみ使う」と書けば、勝手に呼ばれるのを防げます。
実例 1:調査専用エージェント(読み取りのみ)
---
name: explorer
description: コードベースの調査。「〇〇はどこで実装されているか」「△△の呼び出し元を洗い出して」のような質問で使う。ファイルの変更は行わない。
tools: Read, Grep, Glob
model: claude-sonnet-5
---
質問に対して、関連するファイルと該当箇所(ファイル名:行番号)を列挙し、
処理の流れを 10 行以内で要約してください。推測は「推測」と明記してください。読み取りツールだけを許可しているので、誤って変更されることがありません。軽量なモデルを指定して費用を抑えています。調査で読んだ大量のファイルはサブエージェント側のコンテキストに残り、メインには要約だけが返ります(コンテキスト管理)。
実例 2:テスト実行エージェント
---
name: test-runner
description: テストを実行して結果を分析する。実装後の検証や、テスト失敗の原因調査で使う。
tools: Read, Bash(npm test:*), Bash(npx vitest:*), Grep
---
指示されたテストを実行し、結果を次の形式で返してください。
- 実行コマンド
- 成功 / 失敗数
- 失敗したテストごとに: テスト名、エラーの要約、原因の推定(該当ファイル:行番号)
テストコードや実装の修正は行わないでください。実例 3:ドキュメント更新エージェント
---
name: doc-writer
description: 実装変更に合わせて README や docs/ 配下のドキュメントを更新する。実装完了後に使う。
tools: Read, Edit, Write, Grep, Glob
model: claude-sonnet-5
---
`git diff` で変更内容を把握し、影響を受けるドキュメントを更新してください。
コードは変更しないでください。更新したファイルの一覧を最後に報告してください。呼び出し方
- 自動: description の条件に合う状況で、メインの Claude が自動的に委任します。
- 明示: 「code-reviewer エージェントで今の差分をレビューして」と伝えます。
- スキルから呼ぶ:
/reviewのようなスラッシュコマンドの本文で「code-reviewer サブエージェントを使うこと」と指示すると、コマンドとエージェントを組み合わせられます(スラッシュコマンドの作り方)。
使いどころと注意点
| 向いている | 向いていない |
|---|---|
| 広範な調査(結果の要約だけ欲しい) | メインの会話の文脈を前提にした細かい修正 |
| 観点が決まったレビュー | 対話しながら方針を決める作業 |
| 独立して検証できる作業(テスト、lint) | 前後の作業と密結合したステップ |
サブエージェントはメインの会話を知らない
「さっき話した方針で」のような指示はサブエージェントに伝わりません。メインの Claude が委任時に必要な情報をすべて渡す必要があるため、定義ファイルに「委任時には対象ファイルと目的を明記すること」と書いておくと安定します。
サブエージェントは並列に動かすこともできます。ただし、複数のサブエージェントが同時に同じファイルを編集する設計は避けてください。ファイルを跨いだ大きな並列作業は、git worktree による並列作業 の方が安全です。
まとめ
.claude/agents/<名前>.mdに name / description / tools / model と本文を書く- description に「いつ使うか」を具体的に書くと自動呼び出しが安定する
- 調査は読み取り専用 + 軽量モデル、レビューは高性能モデル、のように役割ごとに設定する
- サブエージェントはメインの会話を知らないため、委任時に必要な情報をすべて渡す
よくある質問
- サブエージェントはメインの会話履歴を見られますか?
- 見られません。サブエージェントは独立したコンテキストで動き、メインから渡された指示と自分が読んだ内容だけを持ちます。結果は要約としてメインに返されます。
- サブエージェントはいつ呼ばれますか?
- description に書いた条件に基づいて Claude が自動で判断します。「〇〇エージェントを使って」と明示的に指示することもできます。
- サブエージェントにモデルを指定できますか?
- frontmatter の model で指定できます。調査など軽い作業は Sonnet、判断が必要な作業は Opus、のように使い分けると費用を抑えられます。
読者からの質問と回答
Q. サブエージェントに omitClaudeMd: true を付けたのに、サブディレクトリの CLAUDE.md やパススコープのルールが読み込まれてしまいます。--agent で起動したセッションでも効きません。これは仕様ですか。
omitClaudeMd は 起動時に積む初期コンテキストから外す設定で、セッション中に後から読み込まれるものには効きません。公式ドキュメントの該当箇所は「What loads at startup」という見出しの下にあり、そこが適用範囲です。
frontmatter リファレンスの記述はこうです。「Set to true to launch this subagent without the user, project, and local CLAUDE.md files; managed policy files still load, except for managed subagents」。外れるのはユーザー・プロジェクト・ローカルの CLAUDE.md の 3 つで、管理ポリシーのファイルは残ります。
一方、メモリのドキュメントは、プロジェクト指示を最も強く外す managed-only の設定についても「A subdirectory's CLAUDE.md and .claude/rules/ files, and path-scoped rules, still load on demand」と書いています。サブディレクトリの CLAUDE.md とパススコープのルールは、そのディレクトリのファイルを読んだ時点でオンデマンドに読み込まれます。起動時の除外設定でこれを止める手段は、公式ドキュメントには書かれていません。
--agent で起動した場合はさらに単純です。omitClaudeMd の行には「Ignored when the agent runs as the main session agent via --agent or the agent setting」とあり、「Run the whole session as a subagent」の節にも「CLAUDE.md files and project memory still load through the normal message flow, even when the agent's definition sets omitClaudeMd」と明記されています。無視されるのが仕様です。
---
name: doc-writer
omitClaudeMd: true
---
この文書作成エージェントは、委譲プロンプトに書かれた内容だけで作業します。この設定は、claude --agent doc-writer では効きません。サブエージェントとして呼ばれたときだけ効きます。
守らせたいルールがある場合、公式ドキュメントが案内しているのは委譲プロンプトに書き直す方法です。「If a rule must, such as "ignore the vendor/ directory," restate it in the prompt you give Claude when delegating」。あわせて「The main conversation still has your full CLAUDE.md when it reads these subagents' results, so most rules don't need to reach the subagent itself」とも書かれており、ルールを親会話側に置く設計が前提になっています。
注意
--agent セッションに git status のスナップショットが渡るかどうかは、公式ドキュメントでは確認できませんでした。ドキュメントが git status について書いているのは「非 fork のサブエージェントの初期コンテキストに含まれる」「Explore と Plan だけが省く」「どのサブエージェントに渡すかは変更できない」という点で、スナップショット自体のオン・オフは includeGitInstructions の設定です。
パススコープのルールの仕組みは Claude Code のパススコープルール にまとめてあります。
参考にした一次情報
この記事は公式ドキュメントを基に AI が下書きを作成し、運営者が内容を確認して公開しています。誤りを見つけた場合は お問い合わせからお知らせください。