---
title: "Claude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】"
url: "https://www.issoh.co.jp/tech/details/7911/"
published: 2025-07-29
updated: 2026-10-02
categories: ["Claude"]
publisher: "株式会社一創"
---

# 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）](https://code.claude.com/docs/en/sub-agents)と[npm](https://www.npmjs.com/package/@anthropic-ai/claude-code)のlatest版（2.1.287）に合わせて、作り方・設定項目・呼び出し方・上限値を整理します。Claude Code自体の導入がまだなら、先に[Claude Codeの使い方と初期設定の手順](/tech/details/17375/)を済ませてください。

## まとめ：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には次の組み込みサブエージェントがあります。どれもメインの会話の権限ルールを引き継ぎます。

| 名前                | ツール              | モデル                         | CLAUDE.md |
| ----------------- | ---------------- | --------------------------- | --------- |
| Explore           | 読み取り専用           | メインを継承（Claude APIではOpusが上限） | 読まない      |
| Plan              | 読み取り専用           | メインを継承                      | 読まない      |
| general-purpose   | サブエージェントが使える全ツール | モデル解決順に従う                   | 読む        |
| claude            | サブエージェントが使える全ツール | モデル解決順に従う                   | 読む        |
| statusline-setup  | 記載なし             | Sonnet                      | 読む        |
| claude-code-guide | 記載なし             | Haiku                       | 読む        |

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` の定義が複数の場所にあると、優先順位の高い方が使われます。

| 優先順位   | 場所                     | 有効範囲        |
| ------ | ---------------------- | ----------- |
| 1（最優先） | 管理設定（managed settings） | 組織全体        |
| 2      | `--agents` フラグ         | そのセッションのみ   |
| 3      | `.claude/agents/`      | そのプロジェクト    |
| 4      | `~/.claude/agents/`    | 自分の全プロジェクト  |
| 5      | プラグインの `agents/`       | プラグインが有効な場所 |

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

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

### 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文字でも違うと、エラーを出さずに無視されます。

| 項目                | 役割                  | 値の例                      |
| ----------------- | ------------------- | ------------------------ |
| `name`            | 識別子（必須）             | `code-reviewer`          |
| `description`     | 委任する条件（必須）          | いつ使うかを1〜2文で              |
| `tools`           | 使えるツールの許可リスト        | `Read, Grep, Glob`       |
| `disallowedTools` | 除外するツール             | `Write, Edit`            |
| `model`           | 使うモデル               | `sonnet`・`inherit`       |
| `permissionMode`  | 権限モード               | `plan`・`acceptEdits`     |
| `maxTurns`        | ターン数の上限             | `20`                     |
| `skills`          | 起動時に読み込むスキル         | スキル名のリスト                 |
| `mcpServers`      | このエージェント専用のMCP      | 名前参照かインライン定義             |
| `hooks`           | 実行中だけ有効なフック         | `PreToolUse` など          |
| `memory`          | 永続メモリの範囲            | `user`・`project`・`local` |
| `background`      | 常にバックグラウンドで実行       | `true`                   |
| `isolation`       | 一時的なgit worktreeで実行 | `worktree`               |
| `effort`          | 推論の努力度              | `low`〜`max`              |
| `omitClaudeMd`    | CLAUDE.mdを読ませない     | `true`（v2.1.271以降）       |
| `color`           | 画面上の表示色             | `blue` など8色              |

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

### 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のパーミッションモードの違いと設定方法](/tech/details/11246/)を参照してください。

## サブエージェントの呼び出し方（自動委任・@メンション・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つ並べて順番を指示すれば連鎖として実行されます。

| 制限        | 既定値       | 変更方法                                   |
| --------- | --------- | -------------------------------------- |
| 入れ子の深さ    | メインの下に3階層 | `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` |
| 同時実行数     | 20体       | `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` |
| セッション内の総数 | 上限なし      | なし                                     |

入れ子の既定は版によって変わってきました。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` がフォークを起動します。

| 比較項目          | フォーク       | 通常のサブエージェント   |
| ------------- | ---------- | ------------- |
| コンテキスト        | 会話履歴をすべて継承 | 委任メッセージから開始   |
| システムプロンプトとツール | メインと同じ     | 定義ファイルに従う     |
| モデル           | メインと同じ     | `model` 項目に従う |
| プロンプトキャッシュ    | メインと共有     | 別のキャッシュ       |

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

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

| 仕組み         | 実行される場所                      | 向いている用途        |
| ----------- | ---------------------------- | -------------- |
| サブエージェント    | 独立したコンテキスト                   | 結果だけが要る作業の切り出し |
| Skills      | 通常はメイン／context: forkは別コンテキスト | 手順やプロンプトの再利用   |
| Agent Teams | メンバーごとに別インスタンス               | メンバー同士の議論と分担   |
| フォーク        | 会話を複製した別コンテキスト               | 前提を共有した横道の作業   |

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

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

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

次のいずれかに当てはまるプロジェクト・ユーザー・管理スコープの定義ファイルは、セッション中にエラーも警告も出ないまま読み飛ばされます。プラグインのサブエージェントは例外で、`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の設定方法](/tech/details/9864/)にまとめています。

## よくある質問

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

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

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

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

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

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

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

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

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

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

## 関連記事

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

---

出典: [Claude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】](<https://www.issoh.co.jp/tech/details/7911/>)（株式会社一創）