サブエージェントとは──分けると速くなる作業と、分けると壊れる作業

サブエージェントとは、Claude Code が親の会話とは別のコンテキストウィンドウでサイドタスクを実行し、詳細ではなく概要だけを返す仕組みです。速くなるのは「互いに独立していて、出力が大きく、要約だけ戻ればいい作業」。逆に崩れるのは「順番があり、同じファイルを触り、途中の文脈が判断に必要な作業」です。公式ドキュメントは並列調査について「これは、研究パスが互いに依存しない場合に最適に機能します」と条件を明示しており、この条件を外して分割すると、分けたぶんだけ速くなるどころか空振りの調査が並びます。この記事では公式ドキュメントの記述だけを土台に、設定の実際と、分けてはいけない作業の見分け方を整理します。

• サブエージェントはカスタムシステムプロンプト・特定のツールアクセス・独立した権限を備えた独自のコンテキストウィンドウで動き、親の会話には概要のみを返す
• 組み込みは Explore / Plan / general-purpose の3種類。Explore と Plan は読み取り専用で、CLAUDE.md と git ステータスをスキップする
• 定義ファイルは YAML フロントマター + Markdown 本体。必須フィールドは name と description の2つだけで、置き場所は5階層の優先度で解決される

サブエージェントは何をする仕組みなのか

公式ドキュメントは、使う場面を「サイドタスクがメイン会話に検索結果、ログ、または再度参照しないファイルコンテンツで溢れかえる場合」と説明しています。主目的は分業そのものではなく、捨てていい情報を親の会話に持ち込まないことです。

挙げられている用途は5つ。コンテキストを保持する（探索と実装の分離）、制約を強制する（使えるツールを絞る）、設定を再利用する、動作を特化させる、コストを制御する（Haiku のような安価なモデルへのルーティング）。

親から見ると、Claude は各サブエージェントの description を読んで委譲するかを判断します。説明文が曖昧だと呼ばれません。積極的な委譲を促すなら description に「use proactively」のようなフレーズを含めるよう書かれています。AIエージェント全体の考え方はAIエージェントとは、Claude Code そのものの位置づけはClaude Codeとはで別途整理しています。

組み込みの3種類はどう違うのか

カスタム定義を書かなくても、Claude Code には最初から3つのサブエージェントが入っています。

実務で効いてくるのが、Explore と Plan だけが CLAUDE.md ファイルと親セッションの git ステータスをスキップするという仕様です。理由は「研究を高速かつ低コストに保つため」と説明され、同時に注意も書かれています。「vendor/ ディレクトリを無視する」のようなルールが必須なら、委譲時のプロンプトで再度述べる必要がある、と。どのエージェントがスキップするかを変えるフロントマターや設定は存在しません。

Explore は v2.1.198 以降メイン会話のモデルを継承する挙動になり、常に Haiku で走るわけではなくなりました。低コストに固定したいなら、Explore という名前のサブエージェントを model: haiku で定義すれば組み込みを上書きできます。

定義ファイルはどこに置き、何を書くのか

サブエージェントは YAML フロントマターを持つ Markdown ファイルです。置き場所でスコープと優先度が決まります。

必須は name と description の2つだけ。任意フィールドは tools（許可リスト）、disallowedTools（拒否リスト）、model、permissionMode、maxTurns、skills、mcpServers、hooks、memory、background、effort、isolation、color、initialPrompt です。最小構成はこの程度です。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

model は sonnet / opus / haiku / fable のエイリアス、完全なモデルID、または inherit を受け付け、省略時は inherit です。なお v2.1.198 以降、/agents は作成ウィザードを開かなくなりました。消えたのはウィザードだけで、ファイル形式と置き場所は変わっていないと明記されています。

呼び出し方は3段階。名前を挙げる自然言語（委譲するかは Claude が決める）、タイプアヘッドから選ぶ**@-mention**（実行が保証される）、メインスレッド自体を起動する claude --agent <name>（デフォルトのシステムプロンプトを完全に置き換える）です。

分けると速くなるのはどんな作業か

「一般的なパターン」として挙がっているのは3つです。

筆頭が大量出力の分離。テストの実行、ドキュメントの取得、ログ処理はどれも相当なコンテキストを消費しますが、委譲すれば詳細出力はサブエージェント側に留まり、概要だけが親に返ります。「テストスイートを実行して、失敗したテストとエラーメッセージだけを報告して」という頼み方が例示されています。

2つ目が並行研究。認証・データベース・API の各モジュールを別々のサブエージェントで同時に調べる例が挙がっています。ただし条件付きで、「これは、研究パスが互いに依存しない場合に最適に機能します」と書かれています。

3つ目がチェーン。「code-reviewer で性能問題を見つけ、次に optimizer でそれを直す」という例で、各サブエージェントが結果を Claude に返し、Claude が関連するコンテキストを次に渡します。依存があるなら並列ではなく直列、というのが公式の答えです。この設計思想はコンテキストエンジニアリングとはとも地続きです。

分けると壊れるのはどんな作業か

上位記事は成功例に寄りがちですが、公式ドキュメントは失敗する条件のほうを具体的に書いています。整理すると型は5つです。

型1：依存のある調査を並列に投げる。 B の前提が A の結論であるとき、並列に走った B は前提が決まらないまま調査を始めます。「研究パスが互いに依存しない場合に最適」という条件は、裏返せばこの型を避けろという意味です。

型2：同じファイルを複数に書かせる。 エージェントチーム側のドキュメントに直接の記述があります。「順序付きタスク、同じファイルの編集、または多くの依存関係を持つ作業の場合は、単一セッションまたは subagents がより効果的です」。この一文はエージェントチームとの比較の文脈で書かれたものですが、並列化そのものが常に得ではない、と公式が明言している箇所です。

型3：文脈が要る作業を投げる。 サブエージェントは新しい分離されたコンテキストウィンドウで開始します。ドキュメントは「会話履歴、既に呼び出したスキル、または Claude が既に読み込んだファイルは表示されません」と書いています。渡るのは Claude が作る委譲メッセージだけで、ここまでの議論を踏まえた微妙な判断はそもそも伝わりません。

型4：詳細な結果を返すサブエージェントを大量に走らせる。 警告があります。「サブエージェントが完了すると、その結果がメイン会話に返されます。詳細な結果を返す多くのサブエージェントを実行すると、かなりのコンテキストを消費できます」。分離したはずのコンテキストが、返り値の形で親に戻ってきます。

型5：ルール前提の作業を Explore / Plan に投げる。 前述のとおりこの2つは CLAUDE.md を読みません。プロジェクト固有の禁止事項を守らせたいなら、委譲プロンプトに書き直す必要があります。

そもそも使わないほうがいい場面も列挙されています。メイン会話を使うべきなのは、頻繁なやり取りや反復的な改善が必要な場合、複数のフェーズが重要なコンテキストを共有する場合（計画・実装・テスト）、迅速でターゲット化された変更を行う場合、そしてレイテンシが重要な場合です。最後の理由として「サブエージェントは新規に開始し、コンテキストを収集するのに時間がかかる場合があります」と書かれています。分割には固定費がかかるという認識が前提にあります。

さらに AskUserQuestion、EnterPlanMode、ScheduleWakeup などは、tools に書いてもサブエージェントでは使えません。UI やセッション状態に依存するためです。途中で人に聞き返す必要がある作業は、構造的に委譲に向きません。

サブエージェントで解決しないこと・確認できなかったこと

速度やコストの改善幅を示す数値は、公式ドキュメントには見当たりませんでした。 「コストを制御する」「高速かつ低コストに保つ」という記述はありますが、何割速いといった定量値は書かれていません。この記事の「速くなる」も構造上の説明であって、効果の保証ではありません。

バージョン依存が細かい。 今回読んだページには v2.1.172 から v2.1.208 の間で、挙動変更を示すバージョン番号の注記が複数並びます。デフォルトでバックグラウンド実行になったのは v2.1.198 以降、tools の全項目が解決できないときに起動を拒否するようになったのは v2.1.208 以降です。手元の挙動が記事と違う場合は、まず自分のバージョンを確認するのが早いです。

ネストの深さは5で固定。 v2.1.172 以降サブエージェントは自分のサブエージェントを生成できますが、深さ5のサブエージェントは Agent ツールを受け取らず、それ以上生成できません。「制限は固定されており、設定不可能です」と明記されています。

エージェントチームは実験的機能で、デフォルト無効。 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を設定しない限り有効になりません。サブエージェントとの違いは通信の有無で、サブエージェントはメインエージェントにのみ結果を報告し、チームメンバー同士は直接メッセージを送り合います。トークンコストはサブエージェントが「低い」、チームが「高い」と比較表に書かれています。

名前の重複は静かに壊れます。 1つのスコープ内の2ファイルが同じ name を宣言すると Claude Code は1つだけを読み込み、どちらが選ばれるかはファイルシステムの読み取り順で決まります。/doctor が同一ディレクトリ内の重複を報告するとされています。

料金プランやモデル世代を含む全体の前提はClaude Code 使い方・料金・できることにまとめてあります。

---

出典

• カスタムサブエージェントの作成（Claude Code 公式ドキュメント）: https://code.claude.com/docs/ja/sub-agents
• Claude Code セッションのチームを調整する（Claude Code 公式ドキュメント）: https://code.claude.com/docs/ja/agent-teams

但し書き

本記事の仕様・フィールド名・バージョン注記は、2026年8月27日時点で上記2ページを取得して確認した内容に基づきます。Claude Code は更新頻度が高く、記載の挙動は後日変わる可能性があります。実行前に手元のバージョンと公式ドキュメントの現行版で確認してください。速度・コストの改善効果を保証するものではありません。