サブエージェントは、特定タイプのタスクを専門に処理するAIアシスタントです。独立したコンテキストウィンドウ・専用のシステムプロンプト・個別のツール権限を持ち、メインの会話を検索結果やログで埋め尽くすことなく、脇のタスクを別コンテキストで処理して結果だけを返します。この記事では、サブエージェントの仕組みと設定ファイルの書き方、呼び出し方を解説します。
サブエージェントとは
サブエージェントは、特定タイプのタスクを扱う専門AIアシスタントです。脇のタスクが、あとで参照しない検索結果・ログ・ファイル内容でメインの会話を埋め尽くしそうなとき、その作業をサブエージェントに任せます。サブエージェントは自分のコンテキストで作業し、要約だけを返します。同じ指示で同じ種類の作業員を繰り返し起動しているなら、カスタムサブエージェントとして定義しておくとよいでしょう。
各サブエージェントは、次の3つを独立して持ちます。
- 独立したコンテキストウィンドウ - 探索や実装の詳細をメインの会話から切り離す
- 専用のシステムプロンプト - 特定ドメインに特化した指示で振る舞いを定義する
- 個別のツール権限 - 使用できるツールを限定できる
Claudeは、サブエージェントのdescription（説明文）を手がかりに、タスクをいつ委譲するかを判断します。タスクが説明にマッチすると、そのサブエージェントに委譲し、サブエージェントは独立して作業して結果を返します。サブエージェントは1つのセッション内で動作します。
サブエージェントの利点
コンテキストの節約
探索や実装をメインの会話の外に出し、主要な文脈を圧迫しないようにします
制約の強制
サブエージェントが使えるツールを限定し、想定外の操作を防ぎます
設定の再利用
ユーザーレベルのサブエージェントとして、複数プロジェクトで使い回せます
加えて、特化したシステムプロンプトで特定ドメインの振る舞いを作り込む「専門化」と、単純なタスクをHaikuのような高速・低コストなモデルに振り分ける「コスト制御」も利点です。委譲の判断はClaudeが説明文をもとに行うため、いつ使ってほしいかが明確に伝わる説明文を書くことが重要です。
設定ファイルの作り方
サブエージェントは、YAMLフロントマターを持つマークダウンファイルです。Claudeに書いてもらうか、自分でファイルを作成します。ファイルの置き場所によって、そのサブエージェントを使える範囲が決まります。
プロジェクト単位
- 配置先:
.claude/agents/ - そのプロジェクトでのみ利用可能
- バージョン管理に含めてチームで共有・改善できる
- 特定のコードベース専用のサブエージェントに向く
ユーザー単位
- 配置先:
~/.claude/agents/ - 自分の全プロジェクトで利用可能
- 個人用のサブエージェントに向く
- 同名を避ければサブフォルダで整理も可能
ファイルは自分で作成するか、Claudeに依頼して作ってもらえます。Claude Codeは~/.claude/agents/と.claude/agents/を監視しており、ファイルを追加・編集すると数秒以内に変更を検知し、次の委譲から新しい定義が使われます（再起動は不要）。ただし、セッション開始時点で~/.claude/agents/ディレクトリが存在しなかった場合は、新しいサブエージェントが見つからないことがあります。その場合はClaude Codeを再起動してください。
フロントマターの設定項目
フロントマターがサブエージェントのメタデータと構成を定義し、本文がシステムプロンプトになります。主な設定項目は次のとおりです。
name- サブエージェントの識別名。ツリー全体で一意にするdescription- どんなタスクに使うかの説明。Claudeが委譲を判断する手がかりになるtools- 使用を許可するツール（カンマ区切り）。省略するとメインの会話のツールを引き継ぐmodel- 使用モデル（sonnet/opus/haikuなど）。省略するとメインの会話のモデルを引き継ぐ
次は、コードの可読性やパフォーマンスを点検する個人用サブエージェントの例です。
---
name: code-improver
description: ファイルを走査し、可読性・パフォーマンス・ベストプラクティスの改善を提案する。コードの記述・変更後に使う。
tools: Read, Grep, Glob
model: sonnet
---
あなたはコード改善の専門アシスタントです。対象ファイルを読み、
可読性・パフォーマンス・ベストプラクティスの観点で具体的な改善案を挙げてください。本文はそのサブエージェントのシステムプロンプトとして働きます。サブエージェントはこのシステムプロンプトと作業ディレクトリなどの基本的な環境情報だけを受け取り、Claude Code本体のシステムプロンプト全体は引き継ぎません。
呼び出しと委譲の仕組み
サブエージェントは2通りの方法で使われます。
自動委譲
- Claudeがタスクとサブエージェントの
descriptionを照合 - マッチしたときに自動的に委譲する
- 説明文の質が委譲の精度を左右する
明示的な呼び出し
- 使いたいサブエージェント名を会話で指定する
- 特定の作業を確実に任せたいときに使う
Claude Codeには、適切な場面でClaudeが自動的に使う組み込みサブエージェント（探索用のExploreなど）も用意されています。組み込みサブエージェントは、メインの会話の権限を引き継ぎつつ追加のツール制限を受けます。プロジェクトやユーザーが同名のサブエージェントを定義すると、組み込みを上書きできます。
サブエージェントは1つのセッションの中で動作します。多数の独立したセッションを並行実行して一箇所から監視したい場合はバックグラウンドエージェント、セッション同士を連携させたい場合はエージェントチームという別の仕組みを検討します。
活用のベストプラクティス
効果的なサブエージェントを作るためのポイントです。
- 単一責任にする - 1つのサブエージェントには1つの役割を持たせ、指示を明確に保つ
- 説明文を具体的に書く - 「〜のときに使う」「〜の後に使う」など、いつ委譲すべきかを明記してClaudeが正しく判断できるようにする
- ツールを絞る - 必要なツールだけを
toolsに列挙し、想定外の操作を防ぐ - バージョン管理する - プロジェクト用サブエージェントはリポジトリに入れ、チームで共有・改善する
- モデルを使い分ける - 単純なタスクは
haikuのような高速・低コストなモデルに振り分けてコストを抑える
最初から複雑なサブエージェントを目指す必要はありません。よく繰り返す1つの作業を切り出し、短い説明文と限定したツールから始めて、実際の使用を通じて説明文や指示を改善していく反復的なアプローチが有効です。
実例
ここでは、実際に手を動かして試せる具体的な例を紹介します。まず、プロジェクト用のディレクトリを用意し、テスト実行を専門に扱うサブエージェントを作成します。
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md <<'EOF'
---
name: test-runner
description: テストの実行と失敗の分析を専門に行う。コードを変更した後、テストが通るか確認したいときに使う。
tools: Bash, Read, Grep
model: haiku
---
あなたはテスト実行の専門アシスタントです。プロジェクトのテストコマンド
（package.json の scripts、pytest、cargo test など）を特定して実行し、
失敗があれば原因となっているファイルと行、エラーメッセージを簡潔に報告してください。
EOFファイルを保存すると、Claude Codeは数秒以内に変更を検知します。あとは会話の中で明示的に呼び出すか、テスト実行に関連するタスクで自動委譲させます。
> test-runner サブエージェントを使ってテストを実行して組み込みの探索用サブエージェント Explore は、定義なしでもClaudeが必要に応じて自動的に使います。大きなコードベースで特定の実装箇所を探すときは、次のように明示的に依頼できます。
> Explore で認証処理がどこで実装されているか調べて作成済みのサブエージェントは、対話中に /agents コマンドで一覧・管理できます。ユーザー単位で使い回したい場合は、配置先を .claude/agents/ ではなく ~/.claude/agents/ に変えるだけです。