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

コードベース全体を調べさせると、Claude が読んだファイルの内容がすべてコンテキストに残り、その後の作業精度が落ちます。レビューを頼むと、レビュー観点の長い指示が本来のタスクと混ざります。

こうした問題を解決するのが サブエージェントです。サブエージェントは独立したコンテキストと専用の指示を持つ Claude で、メインの Claude が必要に応じて呼び出します。この記事では、定義ファイルの書き方と、効果が出やすい使い方を解説します。

サブエージェントの仕組み

メインの 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	使用モデル。省略するとセッションと同じ

実例 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)	前後の作業と密結合したステップ

サブエージェントは並列に動かすこともできます。ただし、複数のサブエージェントが同時に同じファイルを編集する設計は避けてください。ファイルを跨いだ大きな並列作業は、git worktree による並列作業 の方が安全です。

まとめ

• .claude/agents/<名前>.md に name / description / tools / model と本文を書く
• description に「いつ使うか」を具体的に書くと自動呼び出しが安定する
• 調査は読み取り専用 + 軽量モデル、レビューは高性能モデル、のように役割ごとに設定する
• サブエージェントはメインの会話を知らないため、委任時に必要な情報をすべて渡す