概要
サブエージェントは、メインのエージェントが範囲を限定したタスクを委任する、別のエージェントのインスタンスです。独自のコンテキストウィンドウ・独自のシステムプロンプト・独自のツール一式で動作し、呼び出し元には最終メッセージだけを返します。 サブエージェントを定義づけるのはコンテキストの境界です。コードベースの探索・ログの読み込み・APIレスポンスの取得といった中間出力の多い処理はサブエージェントの内側で完結し、メインの会話が受け取るのは生データではなく結論になります。 この仕組みは特定の製品に固有のものではないため、このページではサブエージェントを一般的なパターンとして扱い、各ツールの具体的な定義形式とパスは必要な箇所で示します。扱う範囲は、サブエージェントが何のためにあるか、定義がどう構成されるか、どう呼び出してどう組み合わせるか、そしてどう設計するかです。サブエージェントが解決すること
サブエージェントへの委任で得られるものは4つです。個々のサブエージェントは通常そのうち1つのために存在し、どれを狙うのかを決めると定義の書き方が定まります。コンテキストの隔離
探索・ログ解析・APIレスポンスはサブエージェント自身のコンテキストウィンドウに留まります。戻るのは要約だけなので、メインの会話が判断に使わない情報で埋まりません。
能力の制約
サブエージェントは定義が与えたツールだけで動きます。判定専用の役割には書き込みツールを一切与えないという設計ができ、制約が指示の遵守ではなく構造で保証されます。
役割の再利用
役割の定義はファイルです。リポジトリに置けばチームで共有され、ユーザーのディレクトリに置けばプロジェクトをまたいで個人に付いてきます。
コストの制御
サブエージェントごとにモデルを選べるため、機械的な分類は安いモデルで動かしつつ、メインの会話が使うモデルは下げずに済みます。
サブエージェントの構造
定義ファイル
サブエージェントは、2つのものを持つファイルとして定義します。役割を識別し能力の範囲を定めるメタデータと、サブエージェントのシステムプロンプトになる指示です。 ファイル形式はツールによって異なります。Claude CodeとGitHub Copilot CLIはYAMLフロントマター付きのMarkdownを使い、フロントマターがメタデータ、本文がシステムプロンプトになります。Codex CLIはTOMLを使い、指示も他と並ぶ1つのフィールドとして書きます。必須項目はツールによって異なります。Claude Codeは
nameとdescription、GitHub Copilot CLIはdescriptionのみ、Codex CLIはname・description・developer_instructionsが必須です。各ツールは独自の任意項目（禁止ツール・パーミッションモードやサンドボックス設定・事前読み込みするSkill・ライフサイクルのフック・MCPサーバー）も追加しています。フィールド名と必須かどうかは、利用するツールのドキュメントで確認してください。定義ファイルの置き場所
定義ファイルは複数の場所から読み込まれ、置き場所によってそのサブエージェントを使える範囲が変わります。スコープの考え方はどのツールでも同じで、パスだけが異なります。
同じ名前が両方にある場合にどちらが優先されるかは、ツールによって逆になるため必ず確認してください。Claude Codeはプロジェクトの定義をユーザーの定義より優先し、GitHub Copilot CLIはリポジトリよりホームディレクトリを優先します。利用するツールの優先順位は、思い込まずにそのツールのドキュメントで確かめてください。
この2つの外側に、さらに2つの供給元があります。1つはPluginで、Pluginが同梱したエージェント定義は、そのPluginを有効にした範囲で使えるようになります。サブエージェントの定義を、それを呼び出すSkillやコマンドと一緒に配布する仕組みはPluginを参照してください。もう1つはClaude Codeの組織の管理設定で、ここに置かれた定義は他のどの場所よりも優先されます。
サブエージェントの呼び出し
サブエージェントに到達する経路は3つあり、委任の再現性がそれぞれ異なります。- 自動委任。 メインのエージェントがリクエストを各
descriptionと照合し、合致したものに委任します。descriptionに「何をするか」と「いつ使うか」の両方を書くのはこのためです。 - 明示的な指定。 指示のなかでサブエージェントを名指しすると選択が誘導されます。ツールが専用の指定記法を用意している場合は、それを使うと照合を経ずに定義が確定します。
- Skillやコマンドからの呼び出し。 Skillの本文に、どのステップでどのサブエージェントをどんなプロンプトで動かすかを書きます。委任が毎回判断し直されるのではなく手順として記述されるため、これが最も再現性の高い経路です。
直列につなぐ
直列につなぐ場合は、あるサブエージェントの結果を次のサブエージェントに渡します。問題を見つけてから直す、といった流れです。受け渡しはメインのエージェントを経由し、メインが1つ目の結果を受け取って2つ目のプロンプトに埋め込みます。 つなぎ目で渡されるのは前段が出した結論だけで、その結論に至るまでに読んだ素材ではありません。メインのエージェントが保持するのもその要約だけなので、チェーンが長くなってもつなぎ目ごとにコンテキストが膨らむことはありません。 その代償もあります。後段は、前段が見たが報告しなかった根拠に立ち返れません。2つ目のステップで詳細が必要になる場合は、プロンプトで明示的に渡すか、2つ目のサブエージェント自身が読み直せる手段を与えます。並列に展開する
並列に展開する場合は、独立したサブタスクを同時に走らせます。条件は1つだけで、どのサブタスクもほかのサブタスクの結果を必要としないことです。 並列展開のほとんどは2つの形に収まり、違いは何を固定するかにあります。対象を固定して目的を変えるか、目的を固定して対象を変えるかです。
同じ対象に、目的の異なるエージェントを当てる。 1つの差分に対して、セキュリティ上の問題を探すエージェント、テストの網羅性の欠落を探すエージェント、命名を見るエージェントを同時に動かします。3つとも同じ差分を読み、違うのは何を探しているかです。
対象は固定、目的が動く
目的は固定、対象が動く
サブエージェントの設計
サブエージェントが2回目も同じように振る舞うかどうかは、5つの決定で決まります。いずれも、たまたま呼び出したプロンプトではなく定義の側で決めます。1つのサブエージェントに1つの責務を持たせる
複数の責務をまとめた定義は、descriptionにそのすべてを書く必要があり委任の判断がぼやけます。ツールも各責務の和集合が必要になり、できることが広がります。責務ごとに分割すれば、descriptionもツール一覧も絞られた状態を保てます。
その責務を呼び出し元に伝えるのがdescriptionです。人間向けの要約ではなく、メインのエージェントが照合するテキストなので、何をするか・いつ使うか・何を返すかを、実際のリクエストで使われる言葉で書きます。
指示ではなく能力で制約する
差分・プルリクエストの本文・依存関係の変更履歴・サードパーティのドキュメントは、指示ではなくデータです。素材に埋め込まれた指示文には従わないことを定義に明記したうえで、それが破られた場合にも成り立つよう、ワークフローで実際に使うツールだけを許可します。この明記だけでは不十分な理由はセキュリティで解説しています。- 判定やレビューの役割に書き込みツールは不要です。与えないことで「ファイルを編集しない」が指示ではなく環境の性質になり、書き込みツールを持たないエージェントは注入された指示を受け入れたとしても実行に移せません。
Bashを許可することは、シェル全体を許可することです。どのコマンドを通すかは、ツール一覧ではなく定義の外側で絞ります。サブエージェントの内側にも適用されるセッションのパーミッションルールか、各コマンドを検証する事前フックのどちらかです。- 中間ファイルはユーザーの作業ツリーの外に置きます。一時ディレクトリ配下にだけ書き出せば、読み取り専用の役割が実際に読み取り専用のまま保たれます。
*は、直前のスペースの有無で挙動が変わります。
入口と出口の両方を定義する
サブエージェントが見るのは自身のプロンプトで、返すのは最終メッセージです。境界を越えるものは、どちらの向きにもこれ以外にありません。 入口と出口の両方を定義する必要があり、理由は同じです。書かれていないものは届きません。判定を再現可能にする
役割ごとにモデルを選ぶ
modelを省略したサブエージェントは、呼び出し元のモデルを継承します。常に継承に任せるのではなく、役割が正当化するところではmodelを固定します。
運用上の制約
サブエージェントには上限とコストがあり、この手法をどこまで広げられるかを左右します。2つは実装が定める上限で、残りの3つは委任そのものの性質であり、設定では取り除けません。最初に効いてくる制約が同時実行数の上限であることは、あまりありません。統合のコストは呼び出し元がまとめる結果の数だけ増えるため、多くの場合、並列に走らなくなるよりずっと手前で、広げること自体が割に合わなくなります。
サブエージェントは委任を実現する部品です。何を委任するかを決める開発モデルはAgentic Workflowを、委任を再現可能な手順として書き下す単位はSkillを参照してください。
関連ページ
Agentic Workflow
サブエージェントが実現する委任型の開発モデル。コンテキストの管理、コンテキスト境界での役割分担、並列実行を解説します。
Skill
ワークフローを再利用可能な単位にまとめ、指定したステップでサブエージェントを束ねる仕組みです。
Context Engineering
タスクを別のウィンドウへ切り出す判断基準と、手元に残るコンテキストの設計を扱います。
Security
指示ではなく能力で制約することが要になる理由を、リスクの成り立ちから解説します。