ガイド

Claude Code のサブエージェント：作り方、設定、使い方

公開日：2026年10月30日 · 最終確認：2026年10月30日

サブエージェントは、1 種類のタスクを専用のコンテキストウィンドウで処理し、要約だけをメインの会話に返す、専門化された AI アシスタントです。このページでは、Anthropic の Create custom subagents のドキュメントに沿って、サブエージェントとは何か、組み込みのサブエージェント、自作の方法、ファイルの置き場所、frontmatter の書き方、モデルの選び方、呼び出し方、見つからないときの確認点を説明します。ドキュメントは 2026 年 10 月 30 日に確認しました。

サブエージェントとは何か、いつ使うか

ドキュメントの基準は次のとおりです。二度と参照しない検索結果、ログ、ファイルの内容でメインの会話があふれてしまうような副次的なタスクには、サブエージェントを使います。サブエージェントはその作業を自分のコンテキストで行い、要約だけを返します。同じ種類のワーカーを同じ指示で何度も起動しているなら、カスタムのサブエージェントを定義します。

各サブエージェントは、独自のシステムプロンプト、特定のツールアクセス、独立した権限を持つ専用のコンテキストウィンドウで動作します。リクエストも自分で送り、それはメインの会話と同じ使用量の上限に加算されます。Claude は、サブエージェントの description に合致するタスクに出会うと、そのサブエージェントに委任し、サブエージェントは独立して作業して結果を返します。ドキュメントは、次の利点を挙げています。

• 探索や実装をメインの会話から切り離して、コンテキストを節約する
• サブエージェントが使えるツールを制限して、制約を強制する
• ユーザーレベルのサブエージェントで、プロジェクトをまたいで設定を再利用する
• 特定の領域に絞ったシステムプロンプトで、動作を専門化する
• Haiku のような、より速く低コストのモデルにタスクを振り分けて、コストを抑える

ドキュメントからもう 1 点：サブエージェントは、単一のセッションの中で動作します。多数の独立したセッションを並列で実行し、1 か所から監視したい場合は、バックグラウンドエージェントを案内しています。Claude が起動して監督する、連携したセッションのチームが必要な場合は、エージェントチームを案内しています。

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

Claude Code には、Claude が適切なときに自動で使う、組み込みのサブエージェントが含まれています。それぞれが親の会話の権限ルールを継承し、ほとんどは制限されたツールセットで動作します。

Explore と Plan は、調査を速く低コストに保つため、CLAUDE.md ファイルと git status のスナップショットなしで始まります。他の組み込みとカスタムのサブエージェントは、その両方を読み込みます。Explore を呼び出すとき、Claude は徹底度のレベルを指定します。的を絞った検索には quick、バランスの取れた探索には medium、包括的な分析には very thorough です。

ドキュメントはまた、通常は自動で呼び出されるヘルパーエージェントも挙げています。

特定の組み込みタイプをブロックするには、下の FAQ のように permissions.deny に追加します。組み込みの Explore と Plan のサブエージェントだけを取り除くには、CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 を設定します。すると Claude は、ファイルを直接読み、探索します。Claude Code v2.1.198 以降が必要です。

最初のサブエージェントを作る

サブエージェントは、YAML の frontmatter を持つ Markdown ファイルです。Claude に書かせることも、自分でファイルを書くこともできます。この手順はドキュメントにあるもので、コードをレビューして改善を提案する、ユーザーレベルのサブエージェントを作ります。

まず Claude Code で、欲しいサブエージェントと保存先を説明します。

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude は、name、description、tools のリスト、model、システムプロンプトを含むファイルを書きます。次に、~/.claude/agents/code-improver.md を開いて、frontmatter が依頼した内容と一致しているか確認します。結果は次のようになります。

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

ファイルが ~/.claude/agents/ にあるので、このサブエージェントは、マシン上のすべてのプロジェクトで使えます。代わりに 1 つのプロジェクトに限定するには、そのプロジェクトの .claude/agents/ ディレクトリに移します。最後に、Claude にそれへ委任するよう頼みます。

Use the code-improver agent to suggest improvements in this project

Claude は新しいサブエージェントに委任し、サブエージェントはコードベースをスキャンして、改善の提案を返します。トランスクリプトでは、委任は、サブエージェントの名前に短いタスクの説明が続く、code-improver(Suggest code improvements) のようなツール呼び出しの行として表示されます。

/agents について：ドキュメントによると、/agents を実行すると、Claude に頼むか、.claude/agents/ と ~/.claude/agents/ を直接編集するよう促すリマインダーが表示されます。Claude Code v2.1.197 以前では、/agents は対話型のウィザードを開き、実行中のサブエージェントを一覧する Running タブと、サブエージェントの作成、編集、削除をする Library タブがあります。

変更後に再起動する必要はありません。ドキュメントによると、Claude Code は ~/.claude/agents/ と .claude/agents/ を監視しており、ディスク上でサブエージェントのファイルを追加または編集したとき、あるいは Claude にファイルを書かせたときに、数秒以内に変更を検出し、次の委任は更新された定義を使います。それでも再起動が必要なケースが 3 つあり、トラブルシューティングのセクションにあります。

サブエージェントのファイルの置き場所

サブエージェントのファイルの場所で、誰が使えるかが決まり、その frontmatter で、何ができるかが決まります。同じ名前のサブエージェントが複数ある場合、Claude Code は、優先順位の高い場所のものを使います。

• プロジェクトのサブエージェント（.claude/agents/）は、特定のコードベース専用のサブエージェントに最適です。ドキュメントでは、チームが共同で使って改善できるよう、バージョン管理にチェックインすることを勧めています。
• ユーザーのサブエージェント（~/.claude/agents/）は、すべてのプロジェクトで使える個人用のサブエージェントです。
• Claude Code は .claude/agents/ と ~/.claude/agents/ を再帰的にスキャンするので、定義を agents/review/ や agents/research/ などのサブフォルダに整理できます。サブディレクトリのパスは、サブエージェントの識別にも呼び出しにも影響しません。識別は name の frontmatter フィールドだけで決まるからです。
• name の値は、ツリー全体で一意にしてください。同じ .claude/agents/ ディレクトリの下（サブフォルダを含む）の 2 つのファイルが同じ名前を宣言すると、Claude Code は片方だけを読み込み、どちらかは、ドキュメントに記載された優先順位ではなく、ファイルシステムの読み取り順で決まります。

プロジェクトのサブエージェントは、現在の作業ディレクトリから上に向かって探索されるので、そこからリポジトリのルートまでの間にあるすべての .claude/agents/ がスキャンされます。これらのネストしたディレクトリの複数が同じ name を定義している場合、Claude Code は、作業ディレクトリに最も近い定義を使います。

特に重要な frontmatter のフィールド

サブエージェントは、ファイルの先頭にある --- マーカーで囲んだ YAML の frontmatter で設定し、システムプロンプトは、閉じの --- の後ろに Markdown で書きます。必須なのは name と description だけです。複数の単語から成るフィールド名は、maxTurns や disallowedTools のようにキャメルケースを使い、表と完全に一致させる必要があります。Claude Code は、認識できないフィールドをエラーを出さずに無視します。

ドキュメントには、autoCompactWindow、omitClaudeMd、color、initialPrompt、experimental など、さらに多くのフィールドが載っていますが、ここでは扱いません。もう 1 点：ファイルの本文が、システムプロンプトになります。サブエージェントが受け取るのは、このシステムプロンプトと、作業ディレクトリなどの基本的な環境の詳細だけで、Claude Code のシステムプロンプトは受け取りません。

ツールを制限する

ツールを制限するには、tools フィールドを許可リストとして、または disallowedTools フィールドを拒否リストとして使います。両方が設定されている場合は、まず disallowedTools が適用され、その後 tools が残りのプールに対して解決されます。両方に挙げたツールは取り除かれます。ドキュメントのこの例は、tools で Read、Grep、Glob、Bash だけを許可します。このサブエージェントは、ファイルの編集も書き込みも、MCP ツールの使用もできません。

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

こちらは disallowedTools を使って、Write と Edit を除くサブエージェントのツールプールを継承します。サブエージェントは、Bash、MCP ツール、プールの残りを保持します。

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

モデルを選ぶ

model フィールドは、サブエージェントが使うモデルを制御します。エイリアス（sonnet、opus、haiku、fable）、claude-opus-5-5 や claude-sonnet-5 のような完全なモデル ID（--model フラグと同じ値を受け付けます）、またはメインの会話と同じモデルを使う inherit を指定できます。Claude がサブエージェントを呼び出すとき、その呼び出し限定で model パラメーターを渡すこともできます。Claude Code は、サブエージェントのモデルを次の順序で決定します。

1. 呼び出しごとの model パラメーター
2. サブエージェントの定義の model frontmatter（inherit はメインの会話のモデルを選びます）
3. モデルのエイリアスまたはモデル ID を設定した場合の、環境変数 CLAUDE_CODE_SUBAGENT_MODEL
4. メインの会話のモデル

サブエージェントがどのモデルで動いているか確認するには、/tasks を実行します。Claude Code は、サブエージェントの行にモデルを表示します（Claude Code v2.1.242 以降が必要です）。すべてのサブエージェントを Haiku で動かすドキュメントの例では、設定ファイルの env ブロックに両方の変数を設定します。

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

CLAUDE_CODE_SUBAGENT_MODEL_FORCE には、Claude Code v2.1.257 以降が必要です。これがオンの間、Claude Code はサブエージェントの定義の model フィールドを無視します。

サブエージェントはメインの会話とは別のモデルで動くことができ、自分でリクエストを送ります。そのため、トークン従量課金で支払っている場合、それらのリクエストは、メインのセッションではなく、サブエージェント自身のモデルとして現れます。これについてはこちらの解説で説明しています。モデルの選び方は、モデルと effort レベルの選び方を参照してください。

自動の委任と明示的な呼び出し

自動の委任。Claude は、リクエストのタスクの説明、サブエージェントの設定の description フィールド、現在のコンテキストに基づいて、タスクを自動で委任します。積極的な委任を促すには、サブエージェントの description フィールドに「use proactively」のようなフレーズを含めます。description は簡潔にしてください。サブエージェントの description の合計（組み込みのものを除く）が 15,000 トークンを超えると、Claude Code は起動時に警告を表示しますが、すべてのサブエージェントを読み込みます。

明示的な呼び出し。自動の委任では足りない場合は、自分でサブエージェントを要求できます。1 回限りの提案から、セッション全体のデフォルトまで、段階的に強まる 3 つのパターンがあります。

• 自然言語：プロンプトでサブエージェントの名前を挙げます。委任するかどうかは Claude が判断します
• @ メンション：1 つのタスクについて、そのサブエージェントが実行されることを保証します
• セッション全体：--agent フラグまたは agent 設定で、セッション全体がそのサブエージェントとして動作します

自然言語には、特別な構文はありません。サブエージェントの名前を挙げれば、通常、Claude は委任します。

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@ メンションするには、@ を入力して、ファイルを @ メンションするときと同じように、候補の中からサブエージェントを選びます。これにより、選択を Claude に任せるのではなく、そのサブエージェントが確実に実行されます。

@"code-reviewer (agent)" look at the auth changes

メッセージ全体は引き続き Claude に渡され、Claude があなたの依頼に基づいてサブエージェントのタスクプロンプトを書きます。@ メンションが制御するのは、Claude がどのサブエージェントを呼び出すかであり、どのプロンプトを受け取るかではありません。ピッカーを使わずに、メンションを手入力することもできます：@agent-<name>。

セッション全体をサブエージェントとして実行するには、--agent <name> を渡します。メインスレッド自体が、そのサブエージェントのツール制限とモデルを引き受けるセッションが始まります。

claude --agent code-reviewer

エージェント名は、起動時のヘッダーに @<name> として表示されるので、有効になっていることを確認できます。プロジェクトのすべてのセッションでこれをデフォルトにするには、.claude/settings.json で agent を設定します。両方がある場合は、CLI フラグが設定より優先されます。

{
  "agent": "code-reviewer"
}

フォアグラウンドとバックグラウンド：フォアグラウンドのサブエージェントは、完了するまでメインの会話をブロックし、権限プロンプトはあなたに渡されます。バックグラウンドのサブエージェントは、あなたが作業を続けている間に並行して動きます。ドキュメントによると、何も設定していない場合、メインの会話から Claude が起動したサブエージェントは、バックグラウンドで始まります。

完全な例：コードレビュアー

この例はドキュメントの Example subagents にあるもので、コードを変更せずにレビューする、読み取り専用のサブエージェントです。Edit と Write を除いたツールアクセスと、何を探し、出力をどう整形するかを正確に指定した詳細なプロンプトを持つ、焦点を絞ったサブエージェントの設計を示しています。.claude/agents/code-reviewer.md として保存します。

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

このファイルでは、model: inherit はメインの会話と同じモデルを使うことを意味し、description の「Proactively」と「Use immediately after writing or modifying code」という言い回しが、Claude にいつ委任するかを伝えています。

ドキュメントからのヒント

ドキュメントのベストプラクティスです。

• 焦点を絞ったサブエージェントを設計する：各サブエージェントは、1 つの特定のタスクに秀でているべきです。
• 1 つのサブエージェントを特定できる description を書く：Claude は description を使って、いつ委任するかを判断します。各 description を、適切なサブエージェントに振り分けられる程度に具体的にし、全体を 15,000 トークンの description の予算に収めてください。
• ツールアクセスを制限する：安全性と集中のために、必要な権限だけを与えます。
• バージョン管理にチェックインする：プロジェクトのサブエージェントをチームと共有します。

ドキュメントの一般的なパターンです。

• 大量の出力を伴う操作を切り離す。テストの実行、ドキュメントの取得、ログファイルの処理は、コンテキストを大きく消費することがあります。これらを委任すれば、冗長な出力はサブエージェントのコンテキストに留まり、関連する要約だけがメインの会話に戻ります。例：Use a subagent to run the test suite and report only the failing tests with their error messages
• 並列で調査する。独立した調査には、複数のサブエージェントを起動して同時に作業させます。例：Research the authentication, database, and API modules in parallel using separate subagents。調査の経路が互いに依存しないときに、最も効果的です。
• サブエージェントを連鎖させる。複数ステップのワークフローでは、Claude にサブエージェントを順番に使うよう頼みます。例：Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

ドキュメントの警告：サブエージェントが完了すると、その結果はメインの会話に戻ります。詳細な結果を返すサブエージェントを多数実行すると、コンテキストを大きく消費することがあり、各サブエージェントは、実行中に自分のトークンも消費します。

使わないほうがよい場合：タスクに頻繁なやり取りや反復的な改善が必要なとき、複数のフェーズがコンテキストを大きく共有するとき、素早い的を絞った変更をするとき、レイテンシが重要なとき（フォークでないサブエージェントはゼロから始まり、コンテキストを集めるのに時間がかかることがあります）は、メインの会話を使います。隔離されたサブエージェントのコンテキストではなく、メインの会話のコンテキストで実行する再利用可能なプロンプトやワークフローには、ドキュメントは代わりにスキルを検討するよう勧めています。

トラブルシューティング

Claude が新しいサブエージェントを見つけられない

Claude Code を再起動して、もう一度試してください。ドキュメントによると、これが起こるのは、セッションの開始前に ~/.claude/agents/ が存在しなかった場合だけです。実行中のセッションは、新しく作られた agents ディレクトリを検出しないからです。再起動が必要なケースは 3 つあります。新しい agents ディレクトリで、そのスコープの最初のエージェントファイルを作ったあと。--add-dir や /add-dir で追加したディレクトリで、サブエージェントを追加または編集したあと。そして、これらのディレクトリをそもそも監視しない、--disable-slash-commands で始めたセッションです。

ファイルが黙ってスキップされる

ドキュメントによると、Claude Code は、frontmatter に次のいずれかの問題があると、セッション内で報告せずにファイルをスキップします。

• name がない：Claude Code は、そのファイルを、エージェントの横に置かれたドキュメントとして扱います。
• 冒頭の --- がファイルの 1 行目にない：Claude Code は、そのファイルを frontmatter なしとして読み取り、ドキュメントとして扱います。
• name が - で始まる、: を含む、または 256 文字を超える：Claude Code はファイルをスキップし、エラーをデバッグログに書き込みます。
• name はあるが description がない：Claude Code はファイルをスキップし、理由をデバッグログに書き込みます。
• 解析できない YAML：Claude Code はファイルからフィールドを一切読み取らずにスキップし、解析エラーをデバッグログに書き込みます。

デバッグログを見るには、--debug を付けて Claude Code を実行します。frontmatter が解析できないファイルを見つけるには、.claude/agents や ~/.claude/agents などのディレクトリに対して claude plugin validate を実行します（Claude Code v2.1.233 以降が必要）。frontmatter は解析できるが name がないファイルは、指摘されません。

フィールドのスペルが間違っていて、何も報告されない

Claude Code は、認識できないフィールドを、エラーを出さずに無視します。読み込まれたサブエージェントについては、シェルで claude --debug を実行し、~/.claude/debug/<session-id>.txt のデバッグログで does not recognize or apply を検索します。ログには、サブエージェントのファイルにある、Claude Code が認識できないトップレベルのフィールドが最大 5 つ挙げられ、サポートされているフィールドに近い場合は、意図したと思われる名前も示されます（Claude Code v2.1.296 以降が必要）。

サブエージェントの起動に失敗する

tools リストのどれもがツールに解決されない場合（たとえば、すべてのエントリのスペルが間違っている、またはサブエージェントが使えないツールを指している場合）、Claude Code は通常、サブエージェントの起動を拒否し、Agent ツールは、解決できなかったエントリを示すエラーを返します。

サブエージェントがあなたのルールや会話を知らない

各サブエージェントは、新しい隔離されたコンテキストウィンドウから始まります。あなたの会話履歴、すでに呼び出したスキル、Claude がすでに読んだファイルは、見えません。Claude がタスクを要約した委任メッセージを作成し、サブエージェントはそこから作業します。「vendor/ ディレクトリを無視する」のようなルールをサブエージェントに届けたい場合は、委任するときに Claude に渡すプロンプトで、もう一度書いてください。

FAQ

参考資料

• Claude Code: Create custom subagents（組み込みのサブエージェント、作成の手順、ファイルの場所と優先順位、frontmatter のフィールド、モデルの順序、呼び出し、一般的なパターン、例、トラブルシューティング）