Claude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】

Claude Codeのサブエージェントは、メインの会話から作業を切り出して、別のコンテキストウィンドウで実行させる仕組みです。定義は .claude/agents/ に置くMarkdownファイル1枚で、先頭のYAML frontmatterに名前・説明・使えるツール・モデルを書き、本文がそのサブエージェントのシステムプロンプトになります。

2026年7月1日公開のv2.1.198で /agents コマンドの作成ウィザードが廃止されました。ウィザードの画面で作る手順を前提にした解説は、現行版ではそのまま使えません。この記事では2026年10月2日時点の公式ドキュメント（Create custom subagents）とnpmのlatest版（2.1.287）に合わせて、作り方・設定項目・呼び出し方・上限値を整理します。Claude Code自体の導入がまだなら、先にClaude Codeの使い方と初期設定の手順を済ませてください。

まとめ：Claude Codeのサブエージェントの要点

• サブエージェントは自分専用のコンテキストウィンドウ・システムプロンプト・ツール権限で動き、結果の要約だけをメインの会話に返します。
• 作り方は .claude/agents/<名前>.md（プロジェクト用）か ~/.claude/agents/（全プロジェクト用）にMarkdownを置くだけです。必須項目は name と description の2つです。
• v2.1.198以降、/agents はウィザードを開かず、Claudeに作成を頼むかファイルを直接編集するよう案内するだけになりました。
• 対話セッションではフォークモードが既定で有効（v2.1.232以降）のため、Claudeが起動するサブエージェントはバックグラウンドで動きます。
• 入れ子は既定で3階層まで、同時実行は20体までです。どちらも環境変数で変えられます。
• 書式の誤ったファイルは、セッション中に警告が出ないまま読み飛ばされます。claude plugin validate .claude/agents で事前に確認できます。

Claude Codeのサブエージェントの仕組みと使いどころ

独立したコンテキストで動き、要約だけを返す構造

サブエージェントは起動時に新しいコンテキストウィンドウを持ち、メインの会話履歴・読み込み済みのファイル・使用済みのスキルを引き継ぎません。Claudeが書いた委任メッセージ、定義ファイルのシステムプロンプト、CLAUDE.md、gitステータスのスナップショットから作業を始めます。検索結果やテストログを大量に読んでも、メインの会話に戻ってくるのは最終報告だけです。

サブエージェントのリクエストは、メインの会話と同じ利用上限に数えられます。コンテキストは節約できますが、トークン消費そのものが減るわけではありません。並列で何体も動かせば、その分だけ使用量が増えます。

サブエージェントを使うべき作業と、メインの会話で済ませる作業の線引き

公式ドキュメントが挙げる判断基準をまとめると、次のようになります。

失敗しやすいのは、設計判断を含む実装をサブエージェントに丸投げするケースです。サブエージェントはメインの会話でまとまった前提を知らないため、委任メッセージにもCLAUDE.mdにも書かれていない制約を、変更に反映できないことがあります。前提の共有が必要な作業は、メインの会話で進めるか、後述のフォーク（/subtask）を使います。すでに会話に出ている内容について質問するだけなら、ツールを使わずに全文脈を見て答える /btw の方が向いています。

組み込みサブエージェントの種類とモデル（Explore・Plan・general-purpose）

定義ファイルを作らなくても、Claude Codeには次の組み込みサブエージェントがあります。どれもメインの会話の権限ルールを引き継ぎます。

ExploreはClaudeがコードベースを探索するときに使い、quick・medium・very thoroughの3段階で探索の深さを指定されます。v2.1.197まではExploreが常にHaikuで動いていましたが、v2.1.198からメインの会話のモデルを継承するようになりました。探索を安いモデルで回したい場合は、Explore という名前で model: haiku を指定した定義をユーザーかプロジェクトのスコープに置くと、組み込み版を上書きできます。

ExploreとPlanだけを無効にするには、環境変数 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 を設定します（v2.1.198以降）。特定の種類だけを止めるなら、settings.jsonの permissions.deny に Agent(Explore) のように書きます。

カスタムサブエージェントの作り方（.claude/agents/のMarkdownファイル）

ウィザード廃止後（v2.1.198以降）の作成手順

現行版での作り方は「Claudeに作成を頼む」か「ファイルを自分で書く」の2通りです。v2.1.197以前の /agents にあった、Runningタブ（実行中の一覧）とLibraryタブ（作成・編集・削除）を持つ画面はありません。ファイルの形式、frontmatterの項目、.claude/agents/ と ~/.claude/agents/ という置き場所は変わっていません。

1. プロジェクト直下に .claude/agents/ ディレクトリを作ります（全プロジェクトで使うなら ~/.claude/agents/）。
2. frontmatterと本文を持つMarkdownファイルを置きます。ファイル名は name と一致していなくても構いません。
3. セッションを起動する前からディレクトリがあれば、数秒で変更が検知され、次の委任から新しい定義が使われます。セッション中にディレクトリを新しく作った場合は、Claude Codeの再起動が必要です。
4. 「code-reviewerサブエージェントで直近の変更を見て」のように名前を出して呼び出し、トランスクリプトに code-reviewer(…) の行が出ることを確かめます。

Claudeに作らせる場合は、保存先・役割・読み取り専用にするか・使うモデルを1文で伝え、生成されたfrontmatterが依頼どおりかを開いて確認します。

保存場所の5スコープと優先順位

同じ name の定義が複数の場所にあると、優先順位の高い方が使われます。

プロジェクトの定義は、作業ディレクトリからリポジトリのルートまで遡って探索されます。同じ名前が複数あれば、作業ディレクトリに近い方が勝ちます。agents/review/ のようなサブフォルダも再帰的に読まれますが、識別に使われるのは name だけです。同じディレクトリ配下で名前が重複すると、どちらが読まれるかはファイルの読み込み順で決まり、文書化された優先順位はありません。チームで共有する定義は .claude/agents/ に置いてバージョン管理に含めます。

プラグインで配布したサブエージェントでは、セキュリティ上の理由から hooks・mcpServers・permissionMode の3項目が無視されます。これらが必要なら、ファイルを .claude/agents/ にコピーして使います。配布の仕組みはClaude Codeプラグインの作り方と社内配布で扱っています。

CLIフラグでセッション限定の定義を渡す方法

ディスクに保存せず、そのセッションだけで使う定義は --agents にJSONで渡します。キーが名前、値が定義で、本文の代わりに prompt を書きます。

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

非対話モード（-p）ではJSONファイルのパスも渡せます（v2.1.281以降）。たとえば claude -p --agents ./agents.json "Review my changes" です。対話セッションではファイルパスは受け付けられません。CIで定義を切り替えながら試すときに使います。

frontmatterの設定項目と書き方

必須は name と description だけです。複数語の項目名は maxTurns のようなキャメルケースで、表記が1文字でも違うと、エラーを出さずに無視されます。

skills に書いたスキルは、説明だけでなく本文全体が起動時に注入されます。memory を設定すると ~/.claude/agent-memory/<名前>/（userの場合）などに専用ディレクトリができ、その中の MEMORY.md の先頭200行か25KBのどちらか少ない方がシステムプロンプトに入ります。公式ドキュメントが推奨する既定値は project です。isolation: worktree の挙動はClaude Codeのgit worktreeで並列エージェント開発を行う方法で詳しく扱っています。

toolsとdisallowedToolsでツールを絞る書き方

tools を省略すると、サブエージェントが使える全ツールとMCPツールを継承します。tools: Read, Grep, Glob, Bash と書けば、Edit・Write・MCPツールは使えません。ただし、Bash経由の編集や書き込みまで禁止する設定ではありません。両方を書いた場合は disallowedTools が先に適用されます。

誤解しやすいのが、disallowedTools に Bash(git push *) のような条件付きの指定を書いた場合です。このとき外れるのは該当コマンドだけでなく、Bashツール全体です。Bashを残したまま特定のコマンドだけを止めるには、settings.jsonの permissions.deny に同じルールを書きます。このルールはメインの会話とサブエージェントの両方に効きます。MCPはサーバー単位でも指定でき、disallowedTools: mcp__github と書けばgithubサーバーのツールだけを外せます。

modelの解決順と、サブエージェントのモデルを1つに固定する設定

サブエージェントのモデルは、次の順で決まります。

1. Claudeが呼び出しごとに渡す model パラメータ
2. 定義ファイルの model（inherit はメインの会話のモデル）
3. 環境変数 CLAUDE_CODE_SUBAGENT_MODEL
4. メインの会話のモデル

v2.1.251より前は環境変数が最優先で、定義ファイルの指定まで上書きしていました。古い解説にある「環境変数を設定すれば全サブエージェントのモデルが変わる」という説明は、現行版では成り立ちません。サブエージェントを1つのモデルに固定するには、CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 を併せて設定します（v2.1.257以降）。この設定でも、フォークと、model: inherit を指定したサブエージェント実行のスキルの2つは、メインの会話のモデルで動きます。

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

もう1つの例外は、opus のようなファミリー名です。メインの会話が同じファミリーのモデルなら、ファミリー名はエイリアスが指す版ではなく、メインの会話とまったく同じモデルに解決されます。実際に動いているモデルは、/tasks の各行で確認できます（v2.1.242以降）。

permissionModeが無視されるケース

permissionMode の値が使われるかどうかは、メインの会話の権限モードで決まります。メインが bypassPermissions・acceptEdits・auto のときは、サブエージェントも同じモードで動き、定義の値は無視されます。メインが default・dontAsk・plan のときは定義の値が使われます。ただし、定義に bypassPermissions と書いても、v2.1.267以降はメインのモードのままです。サブエージェントだけを全許可で動かす抜け道はありません。各モードの違いはClaude Codeのパーミッションモードの違いと設定方法を参照してください。

サブエージェントの呼び出し方（自動委任・@メンション・agent指定）

descriptionで自動委任を促す書き方

Claudeは依頼の内容と、各サブエージェントの description を見て委任先を選びます。自分から積極的に使わせたいときは、descriptionに「use proactively」のような語を入れます。全descriptionはコンテキストに常駐するため、組み込み以外の合計が15,000トークンを超えると起動時に警告が出ます。手順の詳細はdescriptionに書かず、使うときだけ読み込まれる本文（システムプロンプト）に移します。

@メンションとagent指定による明示的な呼び出し

自動委任に任せず確実に使わせる方法は、強制力の弱い順に3段階あります。

• 名前を出して頼む：「test-runnerサブエージェントで失敗しているテストを直して」。委任するかどうかはClaudeが判断します。
• @メンション：@ を入力して候補から選ぶと @"code-reviewer (agent)" の形になり、そのタスクでは必ずそのサブエージェントが動きます。手入力なら @agent-code-reviewer です。
• セッション全体をサブエージェントとして起動：claude --agent code-reviewer で起動するか、.claude/settings.json に "agent": "code-reviewer" を書きます。Claude Code標準のシステムプロンプトが、そのエージェントの本文に置き換わります。

フォアグラウンドとバックグラウンドの既定動作

対話セッションではv2.1.232以降、フォークモードが既定で有効です。この状態では、Claudeが起動するサブエージェントはフォークかどうかに関係なくバックグラウンドで動き、Claudeがフォアグラウンドを選ぶことはできません。例外として、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 の場合や、同一プロセスのチームメンバーが起動した場合はフォアグラウンドになります。権限の確認はメインのセッションに、どのサブエージェントからの要求かを示して表示されます。非対話モード（-p）とAgent SDKではフォークモードが既定で無効で、Claudeは結果が必要なときにフォアグラウンドを選びます。

バックグラウンドのサブエージェントは、使える組み込みツールが絞られます。AskUserQuestion や EnterPlanMode などは、実行位置にかかわらず使えません。実行中のタスクは Ctrl+B でバックグラウンドに回せます。常にバックグラウンドで動かしたい定義には、background: true を書きます。

並列実行・連鎖・入れ子の上限と再開の仕組み

互いに依存しない調査は「認証・データベース・APIの各モジュールを別々のサブエージェントで並列に調べて」のように頼むと、同時に走らせてClaudeが結果を統合します。レビュー担当に問題を洗い出させてから修正担当に渡すような役割分担は、名前を2つ並べて順番を指示すれば連鎖として実行されます。

入れ子の既定は版によって変わってきました。v2.1.172〜v2.1.216は5階層で固定、v2.1.217〜v2.1.218は既定1（入れ子不可）、v2.1.219から3階層です。「サブエージェントは別のサブエージェントを呼べない」という説明は、v2.1.217〜v2.1.218の挙動か、それ以前の古い情報です。入れ子を止めたいときは深さを 1 にするか、そのエージェントの tools から Agent を外します。20体に達した状態で新しく起動すると Concurrent subagent limit reached で失敗します。

終わったサブエージェントの続きをさせると、Claudeは SendMessage でそのエージェントIDに指示を送り、それまでのツール呼び出しと推論を保ったまま再開させます。ExploreとPlanは使い切りでIDを返さないため、再開が前提の作業はgeneral-purposeかカスタム定義に任せます。トランスクリプトは ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl に保存され、既定では30日後に削除されます。

フォーク（/subtask）と通常のサブエージェントの違い

フォークは、それまでの会話をすべて引き継いで起動するサブエージェントです。v2.1.212以降は /subtask の後にタスクを書いて起動します。v2.1.161〜v2.1.211では同じ機能のコマンド名が /fork でした。現行の /fork は、セッション全体を別のバックグラウンドセッションに複製するコマンドです。ただしエージェントビューを無効にしている場合は /subtask が使えず、/fork がフォークを起動します。

前提を説明し直さずに横道の作業を任せたいときはフォーク、ツールや権限を絞った専門の作業者が必要なときは通常のサブエージェント、と分けます。フォークはキャッシュを共有するので、同じ文脈が必要な作業なら新しいサブエージェントより安く済みます。スキルの context: fork は名前が似ていますが、会話を引き継がない別の仕組みです。違いはClaude Code 2.1.0の変更点とcontext: forkの仕組みで解説しています。

Skills・Agent Teamsとサブエージェントの使い分け

手順書を毎回同じように実行させたいだけなら、まずSkillsで足ります。Skillsは通常、メインの会話の中で動きます。ただし、context: fork を指定したスキルは別のサブエージェントで実行され、会話履歴を引き継ぎません。サブエージェントの skills 項目でスキルを読み込ませれば、両方を組み合わせられます（Claude SkillsとSKILL.mdの書き方）。

Agent Teamsは実験的機能で、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定しないと有効になりません。メンバーが直接メッセージを交わし、共有のタスクリストで作業を分担します。公式ドキュメントの比較表では、トークン消費はサブエージェントが「少ない」（結果を要約してメインに返すため）、Agent Teamsが「多い」（メンバーごとに別のClaudeインスタンスが動くため）と整理されています。有効にしていると、Claudeが名前を付けて起動したサブエージェントがチームのメンバーとして立ち上がる点にも注意が必要です。仕組みはClaude Code Agent Teamsの全体像で扱っています。

サブエージェントが読み込まれない・委任されないときの確認手順

次のいずれかに当てはまるプロジェクト・ユーザー・管理スコープの定義ファイルは、セッション中にエラーも警告も出ないまま読み飛ばされます。プラグインのサブエージェントは例外で、name が無い場合やYAMLを解釈できない場合でも、ファイル名を名前として読み込まれます。

• frontmatterに name が無い（エージェントではなく資料扱いになる）
• 開始の --- がファイルの1行目にない
• name が - で始まる、または : を含む（: はv2.1.218以降）
• name はあるが description が無い
• YAMLとして解釈できない

読み飛ばしの理由は、claude --debug で起動したときのデバッグログに出ます。セッションを始める前なら、claude plugin validate にディレクトリを渡して確認できます（v2.1.233以降）。v2.1.284で、引用符を閉じ忘れた定義とタブでインデントした定義を置いて実行すると、次の出力になりました（抜粋）。

$ claude plugin validate .claude/agents
Validating agent: /private/tmp/sa7911/.claude/agents/broken2.md
  ❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected character. At runtime this agent does not load at all — with no frontmatter name it is treated as a co-located reference document and skipped.
✘ Validation failed

このコマンドは構文が正しく name だけが無いファイルを検出しません。name の書き忘れは目視で確認します。ファイルは正しいのに委任されない場合は、次の3点を確認します。

• セッション開始時に agents ディレクトリがあったか（無かったなら再起動）
• description が「いつ使うか」を具体的に書いているか
• permissions.deny に Agent(名前) が入っていないか

tools の綴りをすべて間違えた場合は、ツールが0個になるため起動自体が拒否され、解決できなかった項目名がエラーに出ます（v2.1.208以降）。

用途別のサブエージェント定義例（レビュー・読み取り専用DB）

変更差分をレビューさせる定義です。tools からEditとWriteを除いていますが、Bash経由の書き込みは可能なため、この定義だけでは読み取り専用になりません。

---
name: code-reviewer
description: Reviews changed code for bugs and security issues. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Run git diff to see recent changes,
then report issues by priority: critical, warning, suggestion.

次のフックは特定のSQLキーワードを検出する簡易例です。読み取り専用を保証するものではないため、実運用ではDB側で書き込み権限を持たない接続ユーザーを使います。PreToolUse フックのスクリプトが終了コード2を返すと、そのコマンドはブロックされます。

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') || {
  echo "Blocked: could not parse hook input (is jq installed?)" >&2
  exit 2
}
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi
exit 0

macOSとLinuxでは chmod +x で実行権限を付けておかないと、フックはブロックせずに失敗します。プロジェクトの定義に書いたフックは、そのフォルダのワークスペース信頼ダイアログを承認するまで実行されません。フックのイベントと入力形式はClaude Code Hooksの設定方法にまとめています。

よくある質問

/agentsコマンドでサブエージェントを作成できないのはなぜですか？

v2.1.198（2026年7月1日公開）で作成ウィザードが廃止されたためです。Claudeに作成を頼むか、.claude/agents/ にファイルを直接置きます。既存の定義ファイルはそのまま使えます。

サブエージェントはいくつまで作れて、同時にいくつ動かせますか？

公式ドキュメントに定義ファイルの数の上限は書かれていませんが、組み込み以外のdescriptionの合計が15,000トークンを超えると起動時に警告が出ます。同時実行は既定で20体までです。

サブエージェントを使うと料金や使用量は増えますか？

増えます。サブエージェント自身もトークンを消費し、メインの会話と同じ利用上限に数えられます。安く抑えるなら、定義の model に haiku や sonnet を指定します。プランごとの上限はClaude Codeの料金プラン比較を参照してください。

サブエージェントにCLAUDE.mdは読み込まれますか？

カスタムのサブエージェントとgeneral-purposeは、メインの会話と同じ階層のCLAUDE.mdを読み込みます。ExploreとPlanは読み込みません。カスタム定義で読ませたくない場合は、omitClaudeMd: true を書きます（v2.1.271以降）。メインの会話の自動メモリ（auto memory）と出力スタイルは、フォーク以外のサブエージェントには渡りません。

サブエージェントから別のサブエージェントを呼び出せますか？

呼び出せます。v2.1.219以降の既定では、メインの会話の下に3階層まで入れ子にできます。Codexの同様の機能はCodexサブエージェントとカスタムエージェントの使い方で比較できます。

関連記事

• Claude Codeの使い方｜導入から権限とCLAUDE.md設定まで実務手順
• Claude Code Agent Teamsの全体像と従来のサブエージェントでは不可能だった協調開発の仕組み
• Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年最新】
• Claude Codeのパーミッションモードの違いと設定方法｜auto・acceptEdits・bypassPermissionsの使い分け
• Claude Codeの最新バージョンは2.1系｜確認方法・アップデート手順とstable版の違い