Claude Code サブエージェント 使い方｜Task tool・Agent Teams・並列処理完全ガイド【2026年10月最新】

Claude Code のサブエージェントは、メイン会話とは別のコンテキストウィンドウで副作業をこなし、結果だけを返す専用のAIアシスタントです。.claude/agents/ にMarkdownファイルを1つ置けば作れて、旧称「Task tool」は現在 Agent tool という名前で動いています（v2.1.63で改名）。

2026年10月時点（Claude Code v2.1.302で確認）では、少し前の解説記事と比べて仕様がかなり変わっています。サブエージェントは既定で3階層までネストでき、/agents の対話ウィザードは廃止され、会話を引き継ぐフォークは対話セッションで既定ONになっています。並列処理の手段も、公式ではサブエージェント・Agent View・Agent Teams・Projects・Dynamic workflows の5つに整理されました。

この記事でわかることは次のとおりです。

• 公式が示す「並列で作業する5つの方法」と使い分け
• Task tool／Agent tool／TaskCreate などの名前の整理
• カスタムサブエージェントの作り方と呼び出し方（各3通り）
• frontmatter の全フィールドとモデルの決まり方（v2.1.251で順序が変更）
• ネスト・同時実行数・フォーク・Agent Teams の現行仕様と注意点
• コストの公式目安と、権限・セキュリティの設計

想定読者は、Claude Code を日常的に使っていて「メイン会話の文脈を汚さずに作業を任せたい」「複数のエージェントを並列で動かしたい」と考えているエンジニア・テックリードです。Claude Code そのものが初めての方は、先に Claude Codeとは と Claude Code の使い方ガイド を読むと理解が早くなります。

出典: Claude Code 公式サイト

Claude Code のサブエージェントとは

サブエージェントは、特定の種類のタスクを担当する専用のAIアシスタントです。それぞれが独自のコンテキストウィンドウ、システムプロンプト、使えるツール、権限を持ち、作業が終わると要約した結果だけをメイン会話に返します。

公式ドキュメントが挙げる使いどころは、次の2つです。

• 検索結果・ログ・ファイル内容など、後で参照しない大量の出力でメイン会話が埋まってしまう副作業
• 同じ種類の作業者（レビュアー、調査役など）を繰り返し呼び出したいとき

なお、サブエージェントに追加料金はかかりません。ただし利用量はメイン会話と同じ使用量上限に計上されます。

サブエージェントを使う5つの理由

ネストは既定で3階層まで（以前は「不可」）

以前の版の解説では「サブエージェントは別のサブエージェントを生成できない」とされていましたが、現在は既定でメイン会話から3階層下までネストできます（v2.1.219から）。上限に達した階層では Agent ツールが外れます。

• 階層数は環境変数 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変更できる
• ネストを禁止したいときは CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1
• 経緯: v2.1.172〜v2.1.216 は5階層、v2.1.217〜v2.1.218 は既定1、v2.1.219 で既定3

古い記事の設計（Skills やメイン側からのチェーン呼び出しでネストを回避する）も引き続き使えますが、必須ではなくなりました。

並列処理の5つの方法（全体像）

公式ドキュメントは、Claude Code で並列に作業する方法を5つに整理しています。以前よく紹介されていた「サブエージェント／Agent View／Agent Teams の3層」に、Projects と Dynamic workflows が加わった形です。

補助的な仕組みとして、作業ツリーを分ける Worktrees、セッション間のメッセージ（v2.1.224以降）、1つの大きな変更を5〜30個のworktree分離サブエージェントに分ける /batch もあります。

どれを選ぶかの判断基準

公式の選び方は、3つの質問に答える形です。

公式ブログ（2026年4月7日「How and when to use subagents in Claude Code」）では、10ファイル以上の探索、または3つ以上の独立した作業があるときにサブエージェントへの委任を検討する、という目安が示されています。3つを並列で走らせると、1つ分とほぼ同じ時間で終わるとされています。

名称の整理：サブエージェント・Agent tool・Agent Teams の違い

「Task tool」で検索して来た方が最も混乱しやすいのが名前です。検索でよく見る「Task tool」は、サブエージェントを起動する旧ツール名（現在の Agent tool）を指します。現在は「Task」が付く別のツールもあるため、次の表で区別してください。

組み込みサブエージェント一覧

Claude Code には最初から次のサブエージェントが入っています。自作する前に、まずこれで足りないかを確認しましょう。

注意: Explore は Haiku ではありません。 古い解説では「Explore は Haiku なので安い」とされていましたが、現在はメイン会話と同じクラスのモデルで動きます。安く探索させたいなら、model: haiku を指定した自作の調査用サブエージェントを用意するほうが確実です。

Explore と Plan は、CLAUDE.md と git status のスナップショットを読みません。それ以外のサブエージェントは読み込みます（自作のものは omitClaudeMd で CLAUDE.md を外せます）。

組み込みエージェントを止めたいときは、settings の permissions.deny に Agent(Explore) のように書きます。Explore と Plan をまとめて外す CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1（v2.1.198以降）、SDKや非対話モードで組み込みを全部外す CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 もあります。

出典: Claude Code 公式サイト

カスタムサブエージェントの作成方法（3通り）

現在の作り方は「Claudeに頼む」「Markdownファイルを書く」「--agents にJSONを渡す」の3通りです。以前の /agents 対話ウィザード（Library タブ → Create new agent）は v2.1.197 以前の画面で、現行版では使えません。古い手順記事のスクリーンショットどおりに進まないのはこのためです。

方法1: Claude に作ってもらう

いちばん手軽な方法です。目的と保存場所を伝えれば、Claude が定義ファイルを書きます。

.claude/agents/ に、変更差分を読み取り専用でレビューするサブエージェントを作って。
モデルは sonnet、使えるツールは Read・Grep・Glob だけにして。

できあがったファイルは必ず中身を確認し、tools と description が意図どおりかを見てください。

方法2: Markdownファイルを手で書く

.claude/agents/ に YAML frontmatter 付きの Markdown を置くと、サブエージェントとして読み込まれます。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. Review the given files and
suggest concrete improvements. Return findings grouped by severity.

ファイルの変更は数秒で検知されます。ただし、agents ディレクトリを新しく作った場合などは再起動が必要です。

次の条件に当てはまるファイルは、エラーを出さずにスキップされます。

• name または description がない
• 1行目が --- で始まっていない
• name が - で始まる、: を含む、256文字を超える
• YAML の書き方に誤りがある

読み込まれないときは claude --debug で確認するか、claude plugin validate <ディレクトリ>（v2.1.233以降）で検査します。

方法3: --agents フラグでセッション限定に定義する

試しに使いたいときや、CIで一時的に注入したいときは、起動時にJSONで定義を渡せます。セッションが終われば定義も消えます。

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"
  }
}'

claude -p と組み合わせる場合は、JSONの代わりにファイルパスも渡せます（v2.1.281以降）。非対話モードでサブエージェントのシステムプロンプトに追記する --append-subagent-system-prompt（v2.1.205以降）と --append-subagent-system-prompt-file（v2.1.261以降）もあります。

frontmatterフィールド 完全ガイド

出典: Claude Code Docs「Create custom subagents」

必須は name と description の2つだけです。フィールド名は camelCase で、知らないフィールドは無視されます。2026年10月時点の主なフィールドは次のとおりです。

プラグイン経由で配布されたサブエージェントでは、permissionMode・mcpServers・hooks・initialPrompt は無視されます。MCPサーバーの設定方法は Claude Code の MCP連携ガイド で詳しく扱っています。

実装例：DBマイグレーション専用エージェント

memory や isolation を組み合わせた例です。フルのモデルIDは新モデルが出るたびに変わるため、ここではエイリアスの sonnet で指定しています。

---
name: db-migrator
description: Plans and applies database migrations safely. Use for Postgres/MySQL schema changes.
tools: Read, Grep, Edit, Bash
model: sonnet
permissionMode: acceptEdits
memory: project
isolation: worktree
effort: high
color: blue
maxTurns: 40
---

You are a database migration specialist. Before applying any migration,
analyze the schema diff, identify potential data loss risks, and present
a migration plan. Never run destructive statements against production.

isolation: worktree を付けると、サブエージェントは一時的な git worktree で作業します。変更がなければ自動で片付けられ、変更があればパスとブランチが結果として返ります。本番の作業ツリーを直接触らせずに試したいときに使えます。

なお、サブエージェントはユーザーに質問できません（AskUserQuestion は常に外されます）。プロンプトの「承認を求めてから実行」は、人の確認を挟む仕組みにはなりません。危ない操作は tools から外すか、フックで止めてください。

モデルの決まり方（v2.1.251で順序が変わった）

モデルは次の順で決まります。v2.1.251 より前は環境変数が最優先でしたが、今は frontmatter の model のほうが優先です。

全サブエージェントを1つのモデルに固定したい場合は、CLAUDE_CODE_SUBAGENT_MODEL に加えて CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1（v2.1.257以降）を設定します。拡張思考の設定はメインから引き継がれます（v2.1.198以降）。実行中のサブエージェントがどのモデルで動いているかは /tasks で確認できます。

スコープと優先度（どこに置くか）

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

細かい仕様もいくつか押さえておきましょう。

• プロジェクトの .claude/agents/ は、作業ディレクトリから上へたどって探す。同名なら作業ディレクトリに近いほうが優先
• --add-dir で追加したディレクトリの .claude/agents/ も読み込む
• サブフォルダも再帰的に読むが、識別に使うのは name だけ（プラグインでは my-plugin:review:security のようにサブフォルダ名が入る）

サブエージェントの呼び出し方（3通り）

出典: Claude 公式ブログ「How and when to use subagents in Claude Code」

「必ずこのエージェントで」というときは @メンション、「任せてよい」ときは自然言語、が基本です。プロジェクトで常に特定のエージェントを使うなら、.claude/settings.json に次のように書きます。

{
  "agent": "code-reviewer"
}

自動委任をうまく働かせるコツは description の書き方です。全サブエージェントの description は合計で15,000トークンの予算内に収める必要があり、エージェントを作りすぎると委任の精度が落ちます（公式ブログも「カスタムエージェントの作りすぎ」を避けるべき場面に挙げています）。

claude --agent で動かすメインエージェントでは、tools: Agent(worker, researcher) のように書くと、起動できるサブエージェントの種類を絞れます。

フォアグラウンド vs バックグラウンド実行

サブエージェントの実行には、メイン会話を止めるフォアグラウンドと、並行して進むバックグラウンドの2種類があります。現在は対話セッションでフォークモードが既定ONのため、Claude が起動するサブエージェントは原則バックグラウンドで動きます（v2.1.232以降）。

• 実行中のタスクは Ctrl+B でバックグラウンドへ回せる
• 状況や結果は /tasks で確認する
• すべてフォアグラウンドに固定したいときは CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
• バックグラウンドのサブエージェントは、使える組み込みツールが決まったセットに絞られる（MCPツールは全部使える）。同じ定義でも前面と裏で使えるツールが違う点に注意

ネストと同時実行数の上限

フォークや再開したサブエージェントは、同時実行数の上限を超えることがあります。並列数を増やすほど使用量の消費も早くなるので、上限を上げる前にコストも見積もってください。

サブエージェントを再開する

通常のサブエージェントは、SendMessage にエージェントIDか名前を渡すと続きから再開できます（Agent Teams は不要）。Explore と Plan は使い切りで、再開できません。

Agent View（バックグラウンドセッション管理）

Agent View は、独立したバックグラウンドセッションを複数立ち上げ、1つの画面で監視する機能です。2026年10月時点でもリサーチプレビューの扱いです。サブエージェントが「1つのセッションの中の委任先」なのに対し、Agent View は「別々のセッションを並べて管理する」点が違います。

起動と操作

# 一覧画面を開く
claude agents

# バックグラウンドで起動（-p とは併用不可）
claude --bg "investigate the flaky test"

# 名前を付けて起動
claude --bg --name "flaky-test-fix" "investigate the intermittent failure in auth tests"

# サブエージェント定義を使って起動
claude --agent code-reviewer --bg "address review comments on PR 1234"

実行中のセッションを裏に回すには /bg（または /background）を使います。個別の操作は claude attach／logs／stop／respawn／rm です。

Agent View の特性

サブエージェントと Agent View の違い

PCを閉じても進めたい長期の作業は、Agent View ではなく claude.ai/code の Projects（Pro/Maxで公開ベータ）や、クラウドで定期実行する Claude Code のルーティン機能 のほうが合います。

出典: Claude Code 公式サイト

Agent Teams の使い方（実験的機能）

出典: Claude Code Docs「Orchestrate teams of Claude Code sessions」

Agent Teams は、リード役のセッションが複数のチームメイト（独立した Claude Code インスタンス）を立ち上げ、メッセージでやりとりしながら作業を分担する機能です。2026年10月時点でも実験的機能で、既定では無効です。本番の重要な作業に組み込むより、PRレビューや調査など失敗しても困らない作業から試すのが安全です。

設定の詳細は Claude Code Agent Teams 完全ガイド にまとめています。ここではサブエージェントとの使い分けと、現行版で気をつけたい点を中心に説明します。

有効化手順

# その場だけ有効にする
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

常に有効にするなら settings.json に書きます。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Agent Teams は対話セッション専用で、claude -p や Agent SDK ではチームメイトを起動しません。

有効化する前に知っておきたい2つの注意点

1. 名前を付けたサブエージェントがチームメイトとして起動する。 有効化すると、Claude が名前を付けて起動したサブエージェントはチームメイト扱いになります。頼んでいなくてもチームができることがあるので、普段使いの設定で常時ONにするかはよく考えてください。戻すには値を 0 にします。
2. 現行モデルでは共有タスクリストが既定で出ない。 共有タスクリストを使う TaskCreate などのツールは、v2.1.268 以降、既定では Opus 4.7・Sonnet 4.6・Haiku 4.5 以前のモデルにだけ提供されます。Opus 5.5 などの現行モデルでは、チームはメッセージだけで調整します。タスクリストを使いたい場合は CLAUDE_CODE_ENABLE_TODO_TOOLS=1 などで有効にします。

チームの構成と操作

• 構成: チームリード／チームメイト／共有タスクリスト（pending・in progress・completed、依存関係、ファイルロック）／メールボックス（~/.claude/teams/{team}/inboxes/{agent}.json）
• 表示: 既定は in-process（どの端末でも使える）。画面分割（split panes）は tmux か、iTerm2 と it2 CLI が必要。teammateMode または claude --teammate-mode auto で切り替える
• 操作: エージェントパネルで↑↓で選び、Enterで中身を見る・直接メッセージ、x で停止、Ctrl+T でタスクリスト
• モデル: 起動時の指示 → サブエージェント定義の model → CLAUDE_CODE_SUBAGENT_MODEL → リードのモデル、の順。チームメイトには Sonnet が推奨されている
• 規模: まず3〜5人、1人あたり5〜6タスクから。トークン消費はほぼ人数に比例する

サブエージェントの定義ファイルは、チームメイトの役割として流用できます。tools と model は反映されますが、skills は反映されないなどの違いがあります。

サブエージェント vs Agent Teams の使い分け

Agent Teams に向いているユースケース

• 並列コードレビュー: セキュリティ／パフォーマンス／テストの観点を別々のメンバーが同時に確認する
• 担当が分かれた新機能の実装: フロントエンド／バックエンド／テストを、触るファイルが重ならないように割り振る
• 仮説が複数あるデバッグ: 原因の候補をメンバーごとに追わせ、結果を見比べる
• 層をまたぐ整合性確認: フロント・API・DBの食い違いを横断的に洗い出す

Agent Teams に向いていないユースケース

• 順番に進める必要がある作業（依存関係が多い）
• 同じファイルを複数人で編集する作業（worktree で分離されないため意図しない上書きが起きる）
• 小さな修正（調整の手間のほうが大きい）

現行の制限事項（2026年10月時点）

Dynamic workflows（大規模な並列処理）

Dynamic workflows は、Claude が書いた JavaScript のスクリプトが多数のサブエージェントを動かし、結果を照合しながら進める仕組みです。2026年5月28日に正式提供が始まりました。サブエージェントを数個呼ぶ程度では足りない、リポジトリ全体の監査や数百ファイル規模の移行に使います。

• 起動方法: プロンプトに ultracode を含める／「workflowを使って」と頼む／/effort ultracode でセッション中ずっと有効にする／組み込みの /deep-research を使う
• スクリプトの部品: agent()・pipeline()・parallel()・phase()
• 進捗の確認: /workflows。保存したワークフローは .claude/workflows/ か ~/.claude/workflows/ に置かれ、/<名前> で再実行できる
• 提供範囲: 全有料プランとAPI・Bedrock・Google Cloud・Foundry。Pro は /config で自分でオンにする（Max・Team・Enterprise・APIは既定でオン）

公式ブログでは、Bun の Jarred Sumner 氏が約75万行を Zig から Rust へ11日で移植し、既存テストの99.8%が通った事例が紹介されています（本番投入前の段階と注記されています）。

サブエージェント・スキル・Agent Teams・Workflows の比較

スキルとの違いをもっと詳しく知りたい方は Claude Code Skills ガイド と Skills と Hooks の違い をどうぞ。

フォーク（会話を引き継ぐサブエージェント）

フォークは、親の会話履歴・システムプロンプト・ツール・モデルをすべて引き継いだサブエージェントです。以前は実験的機能で、環境変数によるオプトインが必要でしたが、現在は既定で有効です。

v2.1.302 時点で、サブエージェントの公式ドキュメント本文には「-p と SDK では既定OFF」という記述が残っており、変更履歴と食い違っています。headless で使う場合は、自分の環境の版と挙動を確認してください。無効にしたいときは CLAUDE_CODE_FORK_SUBAGENT=0 を設定します。

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

フォークからさらにフォークを作ることはできません。isolation: "worktree" を指定して作業ツリーを分けることはできます。

Task tool から Agent tool へのリネーム（v2.1.63）

出典: GitHub「anthropics/claude-code」

v2.1.63 で、サブエージェントを起動するツールの名前が Task から Agent に変わりました。Task(...) の書き方はエイリアスとして今も動くので、権限ルールなどをすぐに書き換えなくても動作します。新しく書く設定では Agent(...) を使いましょう。

# 起動できるサブエージェントを worker と researcher に限定
tools: Agent(worker, researcher), Read, Bash

# 括弧なし：どのサブエージェントでも起動できる
tools: Agent, Read, Bash

# tools に Agent を書かなければ、サブエージェントを起動できない

フックとの互換性注意点

PreToolUse／PostToolUse フックで tool_name を見ている場合、"Task" のままだと一致しないことがあります。条件を "Agent" に直してください。サブエージェントの開始・終了は SubagentStart／SubagentStop のフックイベントで捉えられます。フックの書き方は Claude Code Hooks 活用ガイド で解説しています。

コスト最適化のベストプラクティス

サブエージェントに追加料金はありませんが、使った分はプランの使用量（API利用ならトークン料金）から差し引かれます。 並列にすると終わるまでの時間は縮みますが、消費量は並列数に応じて増えます。

前提となるプランと料金（2026年10月時点）

有料プランには5時間ごとの枠と週の上限があり、Web・デスクトップ・モバイル・Claude Code で同じ枠を共有します。上限を超えた後は、使用量クレジット（標準のAPI料金）で使い続けられます。プランの選び方は Claude Code の料金ガイド で詳しく比べています。

公式が示すコストの目安

/usage の内訳では、サブエージェント・スキル・プラグイン・MCPごとの消費割合を確認できます（Pro/Max/Team/Enterprise）。表示される金額はAPI定価からの推計で、サブスク利用者に実際に請求される額ではありません。

コスト削減の4つのアプローチ

1. 単純な作業のサブエージェントは model: haiku にする

公式も、単純なサブエージェントには model: haiku を勧めています。今は frontmatter の model が環境変数より優先されるため、エージェントごとに frontmatter で指定するのが確実です。全体をまとめて固定したいときだけ CLAUDE_CODE_SUBAGENT_MODEL と CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 を使います。

export CLAUDE_CODE_SUBAGENT_MODEL="sonnet"
export CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1

2. 同じ文脈が要る作業はフォークを使う

フォークは親とプロンプトキャッシュを共有するため、新しいサブエージェントに状況を一から説明させるより安く済みます。サブエージェント・チームメイト・workflow のエージェントのキャッシュは既定で5分ですが、subagentPromptCacheTtl: "1h" で延ばせます（API利用では1時間キャッシュの書き込みは割高）。

3. 並列にしすぎない

• 公式ブログの目安は「10ファイル以上の探索」か「3つ以上の独立した作業」。小さな修正にサブエージェントを使うと、かえって高くつく
• Agent Teams は3〜5人から始める
• 「認証を直して」だけのような曖昧な指示は、試行錯誤が増えて消費が膨らむ。対象ファイルと完了条件を書いて渡す

4. ツールを絞る

# 読み取り専用のレビュアー
tools: Read, Grep, Glob

使わない Edit・Write・Bash を渡さなければ、余計な試行も思わぬ失敗も減ります。コスト全般の見直し方は Claude Code のコスト最適化ガイド にまとめています。

セキュリティと権限の設計

サブエージェントは自分で判断してツールを使うため、権限の継承ルールを知らずに使うと、想定より強い権限で動いてしまうことがあります。Claude Code 全体の対策は Claude Code セキュリティガイド で扱っているので、ここではサブエージェント特有の点を整理します。

権限継承のルール

つまり、メインを bypassPermissions で動かしていると、読み取り専用のつもりで作ったサブエージェントも確認なしで動きます。読み取り専用にしたいエージェントは、permissionMode ではなく tools で書き込み系のツールを外すのが確実です。auto モードの仕組みは Claude Code の auto モードとは で解説しています。

ツール制限のパターン例

# 読み取り専用レビュアー
tools: Read, Glob, Grep

# 書き込みを禁止（disallowedTools が tools より先に適用される）
disallowedTools: Write, Edit

# 起動できるサブエージェントを限定
tools: Agent(worker, researcher), Read, Bash

disallowedTools に Bash(git push *) のような細かい指定を書くと、Bash ツール全体が外れます。コマンド単位で止めたい場合は、PreToolUse フックで判定して終了コード2を返す方法を使います（公式ドキュメントに、書き込み系のSQLだけを止める読み取り専用SQLのサンプルがあります）。

特定のサブエージェントを組織ポリシーで禁止する

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

サブエージェントへの委任そのものを禁止するなら、Agent を deny に入れます。

プロンプトインジェクションへの備え

• サブエージェントの最終報告は、Claude が読む前にスキャンされる（v2.1.210以降）。指示のように見える内容には印が付き、報告が勧めるツール呼び出しも通常の権限チェックを通る
• プロジェクトのエージェント定義に書いたフック（v2.1.218以降）やインラインのMCP設定（v2.1.238以降）は、フォルダを信頼済みにしないと動かない。他人のリポジトリを開いたときに勝手に動かないための仕組み
• Agent Teams では、--dangerously-skip-permissions で起動するとチームメイト全員がその権限で動く。チームメイトの計画はリードが自動で承認し、人の確認は挟まらない
• エージェント同士のメッセージは「別のClaudeセッションから」と明示され、ユーザーの承認の代わりにはならない

権限を広げすぎたエージェントが起こした事故は、AIエージェントのデータ削除事故の事例 にまとめています。

プロジェクト用エージェントはバージョン管理に入れる

.claude/agents/ を Git で管理すると、チーム全員が同じ定義を使えます。これは公式も勧めている運用です。組織で使うなら、管理者設定で配るエージェントと、プロジェクトごとのエージェントを分けておくと管理しやすくなります。チーム導入の進め方は Claude Code のチーム導入ガイド を参照してください。

サブエージェントで作った試作やツールを、社内の実データや既存システムにつないで業務で使う段階になると、権限設計に加えて、誰が保守し、障害時にどう止めて引き継ぐかを決める必要があります。その段階で何を準備すればよいかは AIで作ったアプリを開発会社へ引き継ぐには で整理しています。

実装例：よく使うカスタムエージェント

公式ドキュメントの書き方に合わせた、そのまま使える3つの例です。モデルは用途に合わせて変えてください。

コードレビュアー（code-reviewer）

---
name: code-reviewer
description: Reviews code changes for security vulnerabilities, performance issues, and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer specializing in security and performance.
When invoked:
1. Identify the changed files from the provided context
2. Review each file for security vulnerabilities, performance anti-patterns, and code quality issues
3. Return findings grouped by severity: Critical / Major / Minor
4. For each issue, give the file path, line number, description, and recommended fix

自作のサブエージェントは起動時に git status のスナップショットを受け取るため、変更ファイルを把握するだけなら Bash を渡さなくても動きます。

セキュリティスキャナー（security-scanner）

---
name: security-scanner
description: Scans the codebase for security vulnerabilities. Use before merging pull requests.
tools: Read, Glob, Grep
model: sonnet
---

You are a security scanner. Look for:
- SQL injection risks
- XSS vulnerabilities
- Hardcoded secrets or API keys
- Insecure dependencies
- Authentication bypass patterns

Report every finding with the file path and line number.

リサーチエージェント（researcher）

大量のファイルを読む調査役です。単純な読み取りが中心なので、安いモデルを指定しています。

---
name: researcher
description: Investigates codebases or documentation that require reading many files. Use for research tasks that would flood the main conversation.
tools: Read, Glob, Grep
model: haiku
maxTurns: 30
---

You are a thorough researcher. When given a topic or question:
1. Explore all relevant files and directories
2. Synthesize what you find into a structured report
3. Return a concise summary with key findings and file references

出典: Claude Code 公式サイト

実運用でのトラブルシューティング

作ったサブエージェントが認識されない

多くはファイルの書き方の問題で、エラーなしにスキップされています。name と description があるか、1行目が --- か、name に : が入っていないかを確認してください。claude --debug でスキップの理由を確かめられます。agents ディレクトリを新しく作った直後なら、再起動も必要です。

/agents でウィザードが出てこない

現行版では仕様どおりです。対話ウィザードは v2.1.197 以前の画面で、今は Claude に頼むか、ファイルを直接書いて作ります。Agent View を開きたいなら、スラッシュコマンドではなく端末で claude agents を実行します。

Concurrent subagent limit reached が出る

同時実行の既定上限（20）に達しています。作業を分けて投げるか、必要なら CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で上限を変えます。大量に並列で動かしたいなら、Dynamic workflows のほうが向いています。

サブエージェントが勝手にバックグラウンドで動く

対話セッションでフォークモードが既定ONになったためです（v2.1.232以降）。前面で動かしたいなら CLAUDE_CODE_FORK_SUBAGENT=0、バックグラウンドを全部止めるなら CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を設定します。

環境変数でモデルを指定したのに反映されない

v2.1.251 以降は、frontmatter の model が環境変数より優先されます。環境変数で全体を固定したいなら CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 を併用します。

Agent Teams のチームメイトが表示されない

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が有効になっていない（echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS で確認）
• claude -p や SDK から起動している（対話セッション専用）
• 画面分割を指定しているのに tmux／iTerm2 を使っていない
• VS Code の統合ターミナル・Windows Terminal・Ghostty で画面分割しようとしている

Agent Teams を有効にしたら頼んでいないチームができた

有効化中は、Claude が名前を付けて起動したサブエージェントがチームメイトになります。普段のサブエージェントとして使いたい場合は CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0 に戻します。

/resume でチームメイトが戻らない

in-process のチームメイトは /resume や /rewind で復元されません。長時間のチーム作業では、途中の成果をファイルやコミットとして残しておくと、やり直しが楽になります。

サブエージェントのログを確認したい

記録は次の場所に保存され、cleanupPeriodDays（既定30日）を過ぎると削除されます。

~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

こんな人におすすめ / あまり向かないケース

サブエージェント活用が合う方

• メイン会話の文脈を汚さずに、大量のファイルやログを調べたい
• 読み取り専用のレビュアーやセキュリティチェックを、決まった型で何度も回したい
• 3つ以上の独立した調査・作業を同時に進めたい
• チームで同じエージェント定義を使いたい（.claude/agents/ を Git 管理）
• 作業ごとにモデルを使い分けて、使用量を抑えたい

あまりおすすめしないケース

• 順番に進める必要がある作業を無理に並列にしたい（1つずつ進めたほうが速くて安い）
• 数行の小さな修正しかない（委任の手間とトークンのほうが大きい）
• 同じファイルを複数のエージェントで同時に編集したい（worktree で分けないと上書きが起きる）
• 本番の重要な作業に Agent Teams や Agent View を組み込みたい（実験的機能・リサーチプレビュー）
• 途中でユーザーに確認しながら進める作業を任せたい（サブエージェントは質問できない）

用途別おすすめ選択ガイド

複数のAIエージェントが協調する仕組み全般については マルチエージェントとは で解説しています。

よくある質問（FAQ）

Q1. Task tool は廃止されますか？

2026年10月時点で、サブエージェントを起動するツールは Agent tool という名前で動いており、Task(...) の書き方はエイリアスとして引き続き使えます。廃止の告知は確認できていません。ただし、現在の TaskCreate・TaskList などはタスクリスト管理用の別ツールなので、「Task」と付くツールがすべて旧 Task tool というわけではありません。

Q2. サブエージェントから別のサブエージェントを呼べますか？

呼べます。v2.1.219 以降は、メイン会話から3階層下までが既定の上限です。古い解説にある「ネスト不可」は、現行版には当てはまりません。ネストさせたくない場合は CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 を設定します。なお、フォークからフォークを作ることと、Agent Teams のチームの中にチームを作ることはできません。

Q3. 並列実行するとコストは下がりますか？

下がりません。待ち時間は短くなりますが、消費する使用量は並列数に応じて増えます。抑えたいなら、単純な作業のサブエージェントを model: haiku にする、同じ文脈が要る作業はキャッシュを共有するフォークにする、小さな作業は委任しない、の3つが有効です。

Q4. Agent Teams は本番で使って大丈夫ですか？

2026年10月時点でも実験的機能で、既定では無効です。セッションを再開するとチームメイトが戻らない、タスクの状態更新が遅れる、といった制限も残っています。PRレビューや調査など、失敗しても困らない作業から試すのが安全です。

Q5. .claude/agents/ と ~/.claude/agents/ はどちらに置くべきですか？

チームで共有するならプロジェクトの .claude/agents/、自分だけが全プロジェクトで使うなら ~/.claude/agents/ が基本です。同じ名前がある場合はプロジェクト側が優先されます。

Q6. Explore を使えば安く調べられますか？

現在はそうとは限りません。Explore はメイン会話のモデル（サブスクなどでは Opus エイリアス）で動くため、以前言われていた「Haiku なので安い」は当てはまりません。安く調べたいときは、model: haiku と読み取り専用ツールを指定した調査用サブエージェントを自作します。

Q7. isolation: worktree はいつ使うべきですか？

今の作業ツリーを汚さずに変更を試したいときです。サブエージェントが一時的な git worktree で作業し、変更がなければ自動で片付けられ、変更があればパスとブランチが返ってきます。マイグレーションの検証や大きめのリファクタリングの試行に向いています。

Q8. Agent Teams と Agent View の違いは何ですか？

Agent Teams は、リードがチームメイトに作業を割り振り、メンバー同士がメッセージでやりとりしながら協調する仕組みです。Agent View は、互いに関係のないバックグラウンドセッションを並べて監視する画面で、各セッションは自分（ユーザー）にだけ報告します。「協調させたい」なら Agent Teams、「別々の仕事を任せて後で確認したい」なら Agent View です。

Q9. Agent Teams は何人チームがベストですか？

公式の目安は、まず3〜5人、1人あたり5〜6タスクです。トークン消費はほぼ人数に比例するため、人数を増やすほど効率が上がるわけではありません。チームメイトには Sonnet が推奨されています。

Q10. Dynamic workflows とサブエージェントはどう使い分けますか？

1ターンで数個のタスクを任せる程度ならサブエージェント、数十〜数百のエージェントを動かして結果を照合したいなら Dynamic workflows です。workflows は同時16エージェント、1回1,000エージェントまでが既定の上限で、25エージェントを超えると警告が出ます。Pro プランでは /config でオンにする必要があります。

まとめ

• サブエージェントは別コンテキストで副作業をこなし、要約だけを返す専用AI。.claude/agents/ に Markdown を置けば作れる
• 起動するツールは Agent tool（旧 Task tool、v2.1.63で改名）。Task(...) はエイリアスとして動く。TaskCreate などは別のツール
• 作り方は「Claudeに頼む」「ファイルを書く」「--agents」の3通り。/agents の対話ウィザードは v2.1.197 以前のもの
• ネストは既定3階層まで、同時実行は既定20まで。Explore はメインのモデルで動く
• モデルは frontmatter の model が環境変数より優先（v2.1.251以降）。全体固定は _FORCE=1
• 並列処理は公式に5つの方法がある。結果だけ欲しいならサブエージェント、協調させたいなら Agent Teams（実験的）、別々の仕事を並べるなら Agent View（リサーチプレビュー）、大規模なら Dynamic workflows
• 権限はメインの bypassPermissions・acceptEdits・auto を継承する。読み取り専用にしたいなら tools で絞る

まずは組み込みの Explore・Plan・general-purpose を使い、同じ依頼を何度も書くようになった段階で .claude/agents/ に自作のエージェントを置く、という順番がいちばん無駄がありません。公式ブログでも、まず会話で試し、型が固まってからカスタムエージェント・スキル・フックに移す流れが勧められています。

参照元

• Claude Code 公式ドキュメント: サブエージェント
• Claude Code 公式ドキュメント: Agent Teams
• Claude Code 公式ドキュメント: 並列で作業する方法の比較
• Claude Code 公式ドキュメント: Agent View
• Claude Code 公式ドキュメント: Dynamic workflows
• Claude Code 公式ドキュメント: コスト
• Claude Code CHANGELOG（GitHub）
• Claude 料金プラン
• Anthropic公式ブログ: How and when to use subagents in Claude Code
• Anthropic公式ブログ: Introducing dynamic workflows in Claude Code