Claude Codeを使い込むと、コードレビュー・デバッグ・調査といった「毎回やる作業」を専門のAIに任せたくなります。その仕組みがサブエージェント（Subagents）です。この記事では、サブエージェントとは何か、定義ファイルの作り方、並列実行のコツ、そして「メイン会話とどう使い分けるか」までを実例つきで解説します。
サブエージェントとは
サブエージェントは、特定のタスクに特化させた独立したAIアシスタントです。最大の特徴は、メインの会話とは別のコンテキスト（文脈）で動くことです。
たとえばログを大量に読ませたり、テストを走らせて出力を確認させたりすると、その膨大な出力がメイン会話を圧迫します。サブエージェントに任せれば、処理は独立した場所で行われ、メイン会話には結果の要約だけが返ってきます。会話がクリーンに保たれ、長時間の作業でも文脈が壊れにくくなります。
定義ファイルの置き場所とスコープ
サブエージェントは、YAMLフロントマターを持つMarkdownファイルとして定義します。置く場所によって適用範囲（スコープ）が変わります。
| 置き場所 | スコープ | 用途 |
|---|---|---|
.claude/agents/ |
現在のプロジェクト | プロジェクト固有。Git管理に含めチームで共有 |
~/.claude/agents/ |
すべてのプロジェクト | 自分専用の個人エージェント |
--agents CLIフラグ |
現在のセッションのみ | クイックテスト用 |
チームで共有したいなら.claude/agents/に置いてコミットするのが基本です。個人的に全プロジェクトで使いたいものは~/.claude/agents/に置きます。
フロントマターの書き方
定義ファイルの先頭に、YAMLで設定を書きます。必須はnameとdescriptionの2つだけです。
---
name: code-reviewer
description: コード品質とセキュリティをレビューする。コードを書いた直後に使用
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはシニアコードレビュアーです。
以下の観点でコードをチェックしてください。
- 可読性と命名
- エラーハンドリング
- セキュリティ
- テストカバレッジ
問題を優先度順に報告し、具体的な修正例を添えてください。主要な項目は次のとおりです。
| 項目 | 必須 | 説明 |
|---|---|---|
name |
○ | 小文字とハイフンで書く一意の識別子 |
description |
○ | どんなときに使うべきかの説明。ここが自動起動の判断材料になる |
tools |
× | 使わせるツール。省略すると全ツールを継承 |
model |
× | sonnet / opus / haiku / fable / inherit（既定） |
memory |
× | user / project / local。永続メモリを持たせる |
isolation |
× | worktreeで独立したgitワークツリーで実行 |
ポイントはdescriptionです。 ここに「いつ使うか」を具体的に書くと、Claude Codeが状況に応じて自動でそのサブエージェントを呼び出してくれます。読み取りだけで良い調査系エージェントはtoolsをRead, Grep, Globに絞ると、誤ってファイルを書き換える事故を防げます。
作り方は3通り
1. Claudeに頼んで作ってもらう
一番手軽なのは、日本語で頼むことです。
~/.claude/agents/ に、コードを読んで可読性とパフォーマンスの改善案を出す
code-improver サブエージェントを作って。読み取り専用で sonnet を使って。2. 手動でファイルを作る
上のフロントマター例をそのまま.claude/agents/code-reviewer.mdとして保存すれば完了です。
3. CLIフラグで一時的に定義する
その場限りで試したいときはJSONで渡せます。
claude --agents '{
"code-reviewer": {
"description": "エキスパートコードレビュアー",
"prompt": "シニアコードレビュアーとして振る舞います...",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'組み込みサブエージェント
自分で作らなくても、Claude Codeには最初からいくつかのサブエージェントが用意されています。
- Explore（探索）：ファイル検索・コードベース探索に特化した読み取り専用エージェント
- Plan（計画）：プランモードで実装前の調査を担当する読み取り専用エージェント
- general-purpose（汎用）：探索と変更の両方が必要な複雑なマルチステップタスク向け
「どこに認証処理があるか探して」のような調査は、Exploreが裏で動いて要約だけ返してくれます。
並列実行でスピードアップ
複数のサブエージェントを同時に走らせられるのが強力なポイントです。
認証・データベース・API の3モジュールを、それぞれ別のサブエージェントで
並列に調査してください。各サブエージェントが独立したコンテキストで同時に動き、すべて終わってから結果が統合されます。大規模なコードベースの調査時間を大幅に短縮できます。
メイン会話との使い分け
万能ではありません。次の基準で使い分けましょう。
サブエージェントが向くケース
- テスト実行・ドキュメント取得・ログ解析など、出力が大量になる作業
- 特定のツールだけに制限したい作業
- 自己完結した独立タスク（複数の並列調査など）
メイン会話が向くケース
- こまめな対話・確認が必要な作業
- フェーズをまたいで文脈を共有し続けたい作業
- 短くて対象が絞られた変更
- レイテンシ（応答速度）が重要な作業
まとめ
サブエージェントは、Claude Codeの作業効率を一段引き上げる機能です。.claude/agents/に定義してチームで共有すれば、コードレビューやデバッグの品質を全員で揃えられます。まずはcode-reviewerのような読み取り専用エージェントを1つ作るところから始めてみてください。メイン会話をクリーンに保ちつつ、専門タスクを任せられる感覚がつかめるはずです。
Views: 3
