> ## Documentation Index > Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # Subagentとは — スコープを絞ったタスクの委任 > サブエージェントは、独自のコンテキストウィンドウ・システムプロンプト・ツール範囲を持つ別のエージェントです。メインのエージェントが範囲を限定したタスクを委任し、結果だけを受け取ります。 ## 概要 サブエージェントは、メインのエージェントが範囲を限定したタスクを委任する、別のエージェントのインスタンスです。独自のコンテキストウィンドウ・独自のシステムプロンプト・独自のツール一式で動作し、呼び出し元には最終メッセージだけを返します。 サブエージェントを定義づけるのはコンテキストの境界です。コードベースの探索・ログの読み込み・APIレスポンスの取得といった中間出力の多い処理はサブエージェントの内側で完結し、メインの会話が受け取るのは生データではなく結論になります。 この仕組みは特定の製品に固有のものではないため、このページではサブエージェントを一般的なパターンとして扱い、各ツールの具体的な定義形式とパスは必要な箇所で示します。扱う範囲は、サブエージェントが何のためにあるか、定義がどう構成されるか、どう呼び出してどう組み合わせるか、そしてどう設計するかです。 ## サブエージェントが解決すること サブエージェントへの委任で得られるものは4つです。個々のサブエージェントは通常そのうち1つのために存在し、どれを狙うのかを決めると定義の書き方が定まります。 探索・ログ解析・APIレスポンスはサブエージェント自身のコンテキストウィンドウに留まります。戻るのは要約だけなので、メインの会話が判断に使わない情報で埋まりません。 サブエージェントは定義が与えたツールだけで動きます。判定専用の役割には書き込みツールを一切与えないという設計ができ、制約が指示の遵守ではなく構造で保証されます。 役割の定義はファイルです。リポジトリに置けばチームで共有され、ユーザーのディレクトリに置けばプロジェクトをまたいで個人に付いてきます。 サブエージェントごとにモデルを選べるため、機械的な分類は安いモデルで動かしつつ、メインの会話が使うモデルは下げずに済みます。 ## サブエージェントの構造 ### 定義ファイル サブエージェントは、2つのものを持つファイルとして定義します。役割を識別し能力の範囲を定めるメタデータと、サブエージェントのシステムプロンプトになる指示です。 ファイル形式はツールによって異なります。Claude CodeとGitHub Copilot CLIはYAMLフロントマター付きのMarkdownを使い、フロントマターがメタデータ、本文がシステムプロンプトになります。Codex CLIはTOMLを使い、指示も他と並ぶ1つのフィールドとして書きます。 ```md Claude Code theme={null} --- name: code-reviewer description: Code review specialist. Reviews a diff for quality, security, and maintainability. Use immediately after writing or modifying code. tools: Read, Grep, Glob, Bash model: sonnet --- You are a code reviewer responsible for quality and security. Read the diff for the range given in the prompt, review only the changed files, and report findings. Do not edit files. Group findings by priority (critical / warning / suggestion) and give a specific fix for each. Return only the findings block, with no preamble. ``` ```md GitHub Copilot CLI theme={null} --- name: code-reviewer description: Code review specialist. Reviews a diff for quality, security, and maintainability. Use immediately after writing or modifying code. --- You are a code reviewer responsible for quality and security. Read the diff for the range given in the prompt, review only the changed files, and report findings. Do not edit files. Group findings by priority (critical / warning / suggestion) and give a specific fix for each. Return only the findings block, with no preamble. ``` ```toml Codex CLI theme={null} name = "code_reviewer" description = "Code review specialist. Reviews a diff for quality, security, and maintainability." sandbox_mode = "read-only" developer_instructions = """ You are a code reviewer responsible for quality and security. Read the diff for the range given in the prompt, review only the changed files, and report findings. Do not edit files. Group findings by priority (critical / warning / suggestion) and give a specific fix for each. Return only the findings block, with no preamble. """ ``` メタデータが担う役割はおおむね共通ですが、すべてのツールがそのすべてを備えているわけではなく、フィールド名と必須かどうかも異なります。 | 役割 | 代表的なフィールド | 用途 | | ----- | --------------------------------- | ------------------------------------------------------------------------------------------- | | 識別子 | `name` | サブエージェントを明示的に呼ぶときのハンドルです。 | | 使う場面 | `description` | メインのエージェントはリクエストをこのテキストと照合して委任を判断するため、そもそも呼ばれるかどうかがここで決まります。 | | ツール範囲 | `tools`、Codex CLIでは`sandbox_mode` | サブエージェントに何ができるかです。ツール一覧を省略できるツールでは、サブエージェント向けに提供されているツールを継承します。 | | モデル | `model` | サブエージェントを動かすモデルです。Claude Codeは`haiku`のようなエイリアス・完全なモデルID・`inherit`を受け付け、省略時は呼び出し元のモデルを継承します。 | | 指示 | 本文、または`developer_instructions` | サブエージェントが従うシステムプロンプトです。 | 必須項目はツールによって異なります。Claude Codeは`name`と`description`、GitHub Copilot CLIは`description`のみ、Codex CLIは`name`・`description`・`developer_instructions`が必須です。各ツールは独自の任意項目（禁止ツール・パーミッションモードやサンドボックス設定・事前読み込みするSkill・ライフサイクルのフック・MCPサーバー）も追加しています。フィールド名と必須かどうかは、利用するツールのドキュメントで確認してください。 ### 定義ファイルの置き場所 定義ファイルは複数の場所から読み込まれ、置き場所によってそのサブエージェントを使える範囲が変わります。スコープの考え方はどのツールでも同じで、パスだけが異なります。 | スコープ | 使える範囲 | Claude Code | GitHub Copilot CLI | Codex CLI | | ------ | ----------------------------------- | ------------------- | -------------------- | ------------------ | | プロジェクト | そのリポジトリ。バージョン管理されるため、チームが同じ定義を共有します | `.claude/agents/` | `.github/agents/` | `.codex/agents/` | | ユーザー | そのユーザーの全プロジェクト | `~/.claude/agents/` | `~/.copilot/agents/` | `~/.codex/agents/` | 同じ名前が両方にある場合にどちらが優先されるかは、ツールによって逆になるため必ず確認してください。Claude Codeはプロジェクトの定義をユーザーの定義より優先し、GitHub Copilot CLIはリポジトリよりホームディレクトリを優先します。利用するツールの優先順位は、思い込まずにそのツールのドキュメントで確かめてください。 この2つの外側に、さらに2つの供給元があります。1つはPluginで、Pluginが同梱したエージェント定義は、そのPluginを有効にした範囲で使えるようになります。サブエージェントの定義を、それを呼び出すSkillやコマンドと一緒に配布する仕組みは[Plugin](/ja/ai/plugin)を参照してください。もう1つはClaude Codeの組織の管理設定で、ここに置かれた定義は他のどの場所よりも優先されます。 ## サブエージェントの呼び出し サブエージェントに到達する経路は3つあり、委任の再現性がそれぞれ異なります。 * **自動委任。** メインのエージェントがリクエストを各`description`と照合し、合致したものに委任します。`description`に「何をするか」と「いつ使うか」の両方を書くのはこのためです。 * **明示的な指定。** 指示のなかでサブエージェントを名指しすると選択が誘導されます。ツールが専用の指定記法を用意している場合は、それを使うと照合を経ずに定義が確定します。 * **Skillやコマンドからの呼び出し。** [Skill](/ja/ai/skill)の本文に、どのステップでどのサブエージェントをどんなプロンプトで動かすかを書きます。委任が毎回判断し直されるのではなく手順として記述されるため、これが最も再現性の高い経路です。 ### 直列につなぐ 直列につなぐ場合は、あるサブエージェントの結果を次のサブエージェントに渡します。問題を見つけてから直す、といった流れです。受け渡しはメインのエージェントを経由し、メインが1つ目の結果を受け取って2つ目のプロンプトに埋め込みます。 ```mermaid theme={null} flowchart LR A["サブエージェントA
問題を見つける"] -->|結果| MAIN["メインエージェント"] MAIN -->|結果を入力として| B["サブエージェントB
問題を直す"] B -->|結果| MAIN ``` つなぎ目で渡されるのは前段が出した結論だけで、その結論に至るまでに読んだ素材ではありません。メインのエージェントが保持するのもその要約だけなので、チェーンが長くなってもつなぎ目ごとにコンテキストが膨らむことはありません。 その代償もあります。後段は、前段が見たが報告しなかった根拠に立ち返れません。2つ目のステップで詳細が必要になる場合は、プロンプトで明示的に渡すか、2つ目のサブエージェント自身が読み直せる手段を与えます。 ### 並列に展開する 並列に展開する場合は、独立したサブタスクを同時に走らせます。条件は1つだけで、どのサブタスクもほかのサブタスクの結果を必要としないことです。 ```mermaid theme={null} flowchart LR MAIN["メインエージェント"] --> A["サブエージェントA"] MAIN --> B["サブエージェントB"] MAIN --> C["サブエージェントC"] A -->|結果だけ| BACK["メインエージェント"] B -->|結果だけ| BACK C -->|結果だけ| BACK ``` 並列展開のほとんどは2つの形に収まり、違いは何を固定するかにあります。対象を固定して目的を変えるか、目的を固定して対象を変えるかです。 | | 目的を変える | 対象を変える | | ---------- | --------------- | ---------------- | | 固定されるもの | すべてのエージェントが読む対象 | すべてのエージェントが担う目的 | | プロンプトが運ぶもの | このエージェントが担う目的 | このエージェントが扱う対象 | | 効く場面 | 1回では対象を見きれない | 対象が多くて1回では扱いきれない | **同じ対象に、目的の異なるエージェントを当てる。** 1つの差分に対して、セキュリティ上の問題を探すエージェント、テストの網羅性の欠落を探すエージェント、命名を見るエージェントを同時に動かします。3つとも同じ差分を読み、違うのは何を探しているかです。 ```text 対象は固定、目的が動く theme={null} Run 1 → Dimension: security. Review the diff at main...HEAD. Run 2 → Dimension: test coverage. Review the diff at main...HEAD. Run 3 → Dimension: naming. Review the diff at main...HEAD. ``` 1つのエージェントに3つの目的を持たせると、互いに関係のない関心事でコンテキストが埋まり、見落としが出ます。目的ごとに分ければ、それぞれが1つに集中できます。 **同じエージェントを、異なる対象に当てる。** 組織のリポジトリを列挙し、同じ監査用のエージェントをリポジトリごとに1つずつ動かします。どのエージェントも「このリポジトリのCIのワークフローが規約どおりか」という同じ問いを持ち、違うのはどのリポジトリを読むかです。 ```text 目的は固定、対象が動く theme={null} Run 1 → Repository: web-frontend. Audit its CI workflows against the policy. Run 2 → Repository: billing-api. Audit its CI workflows against the policy. Run 3 → Repository: batch-jobs. Audit its CI workflows against the policy. ``` 1つのエージェントに全リポジトリを順に見せると、進むほどコンテキストが埋まり、後半ほど精度が落ちます。対象ごとに分ければ、どのエージェントも1つ分だけを読みます。 分割の単位は、実行を始める前に呼び出し元が列挙できるものを選びます。組織のリポジトリ、差分に含まれるファイル、バッチ内のレコードなどです。作業をしてみないと一覧を作れない場合は並列の計画自体が立たず、この形は適用できません。 ## サブエージェントの設計 サブエージェントが2回目も同じように振る舞うかどうかは、5つの決定で決まります。いずれも、たまたま呼び出したプロンプトではなく定義の側で決めます。 | 決めること | 何が固定されるか | 決めないとどうなるか | | ----- | --------------------------------------- | --------------------------------- | | 責務 | 何のためのサブエージェントか、そして委任を引き寄せる`description` | 委任の判断がぼやけ、ツール一覧が広がる | | 能力 | どのツールを持つか、注入された指示が何に手を伸ばせるか | 「ファイルを編集しない」が性質ではなく指示のままになる | | 境界 | プロンプトで何が届き、最終メッセージで何が返るか | 実行のたびに結果が変わり、統合のたびにレポートを読み直すことになる | | 再現性 | どう計算するか、情報が欠けたときにどうするか | 同じ入力から違う判定が出る | | モデル | その役割をどのグレードのモデルで動かすか | 広い並列展開が見合わないコストになる | ### 1つのサブエージェントに1つの責務を持たせる 複数の責務をまとめた定義は、`description`にそのすべてを書く必要があり委任の判断がぼやけます。ツールも各責務の和集合が必要になり、できることが広がります。責務ごとに分割すれば、`description`もツール一覧も絞られた状態を保てます。 その責務を呼び出し元に伝えるのが`description`です。人間向けの要約ではなく、メインのエージェントが照合するテキストなので、何をするか・いつ使うか・何を返すかを、実際のリクエストで使われる言葉で書きます。 ### 指示ではなく能力で制約する 差分・プルリクエストの本文・依存関係の変更履歴・サードパーティのドキュメントは、指示ではなくデータです。素材に埋め込まれた指示文には従わないことを定義に明記したうえで、それが破られた場合にも成り立つよう、ワークフローで実際に使うツールだけを許可します。この明記だけでは不十分な理由は[セキュリティ](/ja/ai/security)で解説しています。 * 判定やレビューの役割に書き込みツールは不要です。与えないことで「ファイルを編集しない」が指示ではなく環境の性質になり、書き込みツールを持たないエージェントは注入された指示を受け入れたとしても実行に移せません。 * `Bash`を許可することは、シェル全体を許可することです。どのコマンドを通すかは、ツール一覧ではなく定義の外側で絞ります。サブエージェントの内側にも適用されるセッションのパーミッションルールか、各コマンドを検証する事前フックのどちらかです。 * 中間ファイルはユーザーの作業ツリーの外に置きます。一時ディレクトリ配下にだけ書き出せば、読み取り専用の役割が実際に読み取り専用のまま保たれます。 コマンドのパターンは、プレフィックスがより広いコマンドに一致しない形で書きます。末尾の`*`は、直前のスペースの有無で挙動が変わります。 | パターン | ほかに一致するもの | 結果 | | ------------------------------- | ------------------------------ | ------------------------------- | | `Bash(git diff*)` | `git difftool --extcmd=<コマンド>` | ❌ 読み取りを許すつもりのルールが任意コマンド実行の経路になる | | `Bash(git diff --no-renames *)` | なし（語境界で止まる） | ✅ 見たとおりの読み取り専用の許可のまま | 語境界を効かせているのは`*`の前のスペースです。これがないとプレフィックスに続く任意の文字列に一致するため、「差分を許可する」と読めるルールがそれよりはるかに多くを許可しえます。 ### 入口と出口の両方を定義する サブエージェントが見るのは自身のプロンプトで、返すのは最終メッセージです。境界を越えるものは、どちらの向きにもこれ以外にありません。 ```mermaid theme={null} flowchart LR CTX["呼び出し元の文脈
会話・下した判断・読んだファイル"] -.->|越えない| SUB IN["プロンプト
対象範囲・パス・ルール・モード"] --> SUB["サブエージェント
自身のコンテキストウィンドウ"] SUB --> OUT["最終メッセージ
取り決めた形式"] SUB -.->|復帰時に失われる| WORK["作業中の状態
読み取ったものすべて"] ``` 入口と出口の両方を定義する必要があり、理由は同じです。書かれていないものは届きません。 | 境界 | 定義すること | なぜ必要か | | ----------- | ---------------------------- | ------------------------------------------------------ | | 入口（プロンプト） | 対象範囲・パス・適用するルール・動作モード | サブエージェントは呼び出し元の会話を見られないため、共有された文脈を前提にした指示は実行のたびに結果が変わる | | 出口（最終メッセージ） | 厳密な形式。安定したキーを持たせ、挨拶や後書きを付けない | Skillがテーブルの組み立てや結果の結合のためにメッセージを解析する場合、形式は契約になる | ### 判定を再現可能にする | 状況 | 避けること | 代わりにすること | | -------------- | -------------------------- | ------------------------ | | 件数やしきい値で判定が決まる | 読み取ったテキストからモデルに見積もらせる | ツールで計算させ、出力された値をそのまま使わせる | | 判定に必要な情報が欠けている | フォールバックを決めずに実行のたびに変わる状態にする | 挙動を明示し、安全な方向に倒す | 安全な方向とは、問題が表に出る方向です。要件は「充足」ではなく「判定不能」として報告し、リスクのレベルは下げるのではなく上げます。モデルの仕事は、本当に判断が必要な部分に取っておきます。 ### 役割ごとにモデルを選ぶ `model`を省略したサブエージェントは、呼び出し元のモデルを継承します。常に継承に任せるのではなく、役割が正当化するところでは`model`を固定します。 | 役割 | モデルのグレード | | --------------- | ---------------------------- | | 機械的な分類・構造化された抽出 | 安価なモデル。広い並列展開を割に合わせているのはこれです | | 実質的な判断を伴う分析 | 上位のモデル | ## 運用上の制約 サブエージェントには上限とコストがあり、この手法をどこまで広げられるかを左右します。2つは実装が定める上限で、残りの3つは委任そのものの性質であり、設定では取り除けません。 | 制約 | 意味 | 何を強いるか | | ------------------- | --------------------------------------------- | ----------------------------------------------- | | 同時実行数の上限 | 同時に動かせるサブエージェントの数は決まっている | 上限より広く展開しても完了はするが、実時間の短縮にはつながらない | | 入れ子の深さの上限 | メインの会話から下方向へのチェーンは数階層まで | 組み合わせは、さらにサブエージェントを起動するサブエージェントの内側ではなく呼び出し元に置く | | 文脈が共有されない | サブエージェントが見るのは自身のプロンプトであり、呼び出し元の会話ではない | 呼び出し元が持つ状態は渡し直し、サブエージェントが構築した状態は復帰時に失われる前提で設計する | | サブエージェントの内側でも精度は落ちる | 広すぎるタスクを渡されたサブエージェントは自身のコンテキストウィンドウを埋めて精度を落とす | タスクの範囲を絞る。隔離が守るのは呼び出し元であって、サブエージェント自身ではない | | 委任には最低コストがある | 実行のたびに自身の指示とコードベースの担当分を読み直す | 呼び出し元がツール呼び出し数回で終えられるものは委任しない | 最初に効いてくる制約が同時実行数の上限であることは、あまりありません。統合のコストは呼び出し元がまとめる結果の数だけ増えるため、多くの場合、並列に走らなくなるよりずっと手前で、広げること自体が割に合わなくなります。 サブエージェントは委任を実現する部品です。何を委任するかを決める開発モデルは[Agentic Workflow](/ja/ai/agentic-workflow)を、委任を再現可能な手順として書き下す単位は[Skill](/ja/ai/skill)を参照してください。 ## 関連ページ サブエージェントが実現する委任型の開発モデル。コンテキストの管理、コンテキスト境界での役割分担、並列実行を解説します。 ワークフローを再利用可能な単位にまとめ、指定したステップでサブエージェントを束ねる仕組みです。 タスクを別のウィンドウへ切り出す判断基準と、手元に残るコンテキストの設計を扱います。 指示ではなく能力で制約することが要になる理由を、リスクの成り立ちから解説します。