Claude Code のサブエージェントの使い方と作り方(設定・呼び出し・注意点)

公開: 2026年10月15日 ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

サブエージェントとは何か:何ができるか

公式ドキュメントによると、サブエージェントは特定の種類のタスクを担当する専用の AI アシスタントです。Claude Code(Anthropic 社が提供する、ターミナルで動く AI コーディングエージェント)では、検索結果・ログ・ファイルの中身があとで参照しないまま会話を埋めてしまう場面で使います。サブエージェントは自分のコンテキストで作業し、要約だけを返します。

各サブエージェントは、独自のコンテキストウィンドウ、システムプロンプト、ツールアクセス、独立した権限で動きます。ツールを絞って制約をかけたり、Haiku のような高速で低コストなモデルに振ってコストを抑えたりもできます。同じ種類の作業役を同じ指示で何度も呼ぶようになったら、カスタムサブエージェントを定義する目安です。

注意点として、サブエージェントも自分でリクエストを送り、メインの会話と同じ利用上限に数えられます。また、サブエージェントは単一のセッション内で動きます。

出典: Create custom subagents

組み込みサブエージェントと止め方

Claude Code には組み込みのサブエージェントがあり、Claude が適切と判断したときに自動で使います。Explore はコードベースの検索・分析向けの読み取り専用エージェントで、Write と Edit は拒否されます。Plan はプランモードで調査に使う読み取り専用のエージェントです。General-purpose は探索と変更の両方が要る複数ステップの作業向けです。Explore と Plan は、調査を速く安く保つため CLAUDE.md と git status のスナップショットなしで起動します。

特定のサブエージェントを使わせたくない場合は、permissions.deny に Agent(Explore) のような形式で追加します。

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Agent ツール自体を deny すると、Claude はどのサブエージェントにも委任しなくなります。

出典: Create custom subagents

最初の1つを作る手順

公式ドキュメントのクイックスタートでは、Claude に頼んで作らせます。サブエージェントは YAML フロントマター付きの Markdown ファイルなので、手で書くこともできます。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 を開き、頼んだ内容と合っているか確認します。結果は次のようになります。

---
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 のように委任を頼みます。

出典: Create custom subagents

設定:置き場所・ツール・モデル・権限

必須のフィールドは name と description だけです。Claude は description を見て委任の判断をするため、いつ使うかを明確に、かつ短く書きます。組み込みのものを除いたサブエージェントの説明文の合計が 15,000 トークンを超えると起動時に警告が出るので、詳細はシステムプロンプト側に書きます。

置き場所と優先順位

同名のサブエージェントがあると、優先度の高い場所のものが使われます。

• 組織の managed settings:組織全体、優先度1(最高)
• --agents CLI フラグ:現在のセッションのみ、優先度2
• .claude/agents/:現在のプロジェクト、優先度3
• ~/.claude/agents/:自分の全プロジェクト、優先度4
• プラグインの agents/ ディレクトリ:プラグインが有効な範囲、優先度5(最低)

プロジェクト用はバージョン管理にチェックインすると、チームで共有・改善できます。

ツール・モデル・権限モード

tools は許可リスト、disallowedTools は拒否リストです。tools を省略すると、サブエージェントが使える全ツールを継承します。両方を指定した場合は disallowedTools が先に適用されます。model には sonnet、opus、haiku、fable、フルモデル ID、inherit を指定できます。省略時の決まり方は公式ドキュメントで確認してください。

permissionMode を省略すると、メインの会話の権限モードを引き継ぎます。メインの会話が bypassPermissions、acceptEdits、または auto モードのときは、サブエージェントも同じモードで動き、設定値は無視されます。

出典: Create custom subagents

呼び出し方と運用上の注意

呼び出し方は3段階です。自然言語で名前を挙げる方法、@-mention で1回のタスクに必ずそのサブエージェントを使わせる方法、--agent フラグか agent 設定でセッション全体をそのサブエージェントとして動かす方法です。

claude --agent code-reviewer

--agent を使うと、プロンプトが空の場合を除き、カスタムサブエージェントのシステムプロンプトがデフォルトの Claude Code のシステムプロンプトを完全に置き換えます。

サブエージェントは新しいコンテキストで始まり、会話履歴は見えません。Claude が作業内容を要約した委任メッセージから始めます。

運用では次の点に気をつけてください。サブエージェントを多数走らせて詳細な結果が戻ると、メインの会話のコンテキストを大きく消費し、各サブエージェントも自分のトークンを使います。同時に動かせる数は既定で 20 で、超えると Concurrent subagent limit reached で失敗します。変更するには CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS を設定します。

やり取りを何度も重ねる作業、複数フェーズでコンテキストを共有する作業、小さな修正はメインの会話向きです。出力が長い作業、ツール制限をかけたい作業、要約だけ返せば済む作業はサブエージェント向きです。

執筆時点(2026年10月)の公式ドキュメントに基づいており、機能によって必要な Claude Code のバージョンが異なります。社内に配る前に、使っているバージョンで動くか公式ドキュメントで確認してください。

出典: Create custom subagents

参考(執筆時点)

• Create custom subagents(公式ドキュメント)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。