AIニュース

Claude Codeのサブエージェントの使い方|定義ファイルの作り方と呼び出し方

調べ物とコードの修正を同じ会話で進めていると、検索結果やファイルの中身で画面が埋まり、肝心の指示が埋もれてしまいます。Claude Code のサブエージェントの使い方を押さえると、こうした脇の作業を別のコンテキストに切り出し、手元には要約だけを受け取れます。公式ドキュメントでは、サブエージェントは特定の種類のタスクを扱う専用のAIアシスタントと説明され、それぞれが自分のコンテキストウィンドウ(AIが一度に読める文章の範囲)、専用のシステムプロンプト、使えるツールの範囲、独立した権限を持って動きます(公式ヘルプ)。この記事では、定義ファイルの置き場所から書き方、呼び出し方、1人で開発や調査をするときの役割分担までを順に追います。

この記事で分かること

  • サブエージェントが何をしてくれて、どんな作業に向くのか
  • .claude/agents に置く定義ファイルの作り方と必須の項目
  • 作ったサブエージェントの呼び出し方と確認の手順
  • 調べ役とレビュー役を分けるときの考え方とプロンプト例

要点(先に結論)

  • サブエージェントは特定の種類のタスクを扱う専用のAIアシスタントで、独自のコンテキストウィンドウ、専用のシステムプロンプト、特定のツールアクセス、独立した権限を持つ(公式ヘルプ)
  • 定義ファイルは YAML frontmatter(ファイル先頭の設定部分)を付けた Markdown ファイルで、必須の項目は name と description の2つだけ
  • ~/.claude/agents/ に置けば自分のすべてのプロジェクトで使え、プロジェクトの .claude/agents/ に置けばそのプロジェクトだけで使える
  • Claude は各サブエージェントの description を見て、いつ委任するかを決める
  • サブエージェントは自分のリクエストを送り、メインの会話と同じ使用量の上限にカウントされる

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

Claude Code は、機能の実装やバグの修正、開発作業の自動化を手伝うAIのコーディングアシスタントです(公式ヘルプ)。サブエージェントは、その中で本題から外れた作業を別の担当に渡すための仕組みです。

サブエージェントの働きの図解:コンテキスト(探索と実装をメインの会話の外に置いてコンテキストを保つ)、ツール制限(使えるツールを限定して制約を課す)、設定の再利用(ユーザーレベルの定義を複数のプロジェクトで再利用する)、コスト調整(Haikuのような高速で低コストのモデルにタスクを振る)

サブエージェントが向く作業

公式ドキュメントは、脇のタスクが検索結果やログ、あとで参照しないファイルの中身でメインの会話をあふれさせてしまうときに使うよう案内しています。サブエージェントはその作業を自分のコンテキストの中で行い、要約だけを返します。同じ指示で同じ種類の担当を何度も立ち上げているなら、カスタムのサブエージェントとして定義しておくとよい、という説明です。

ドキュメントが挙げる効き目は次の5点です。

  • 探索と実装をメインの会話の外に置いてコンテキストを保つ
  • 使えるツールを限定して制約を課す
  • ユーザーレベルのサブエージェントで設定をプロジェクト間で再利用する
  • 特定の領域に絞ったシステムプロンプトで振る舞いを専門化する
  • Haiku のような高速で低コストのモデルにタスクを振ってコストを抑える

タスクが説明に一致すると、Claude はそのサブエージェントに委任し、サブエージェントは独立して作業して結果を返します。委任の様子は、サブエージェントの名前と短いタスクの説明を並べたツール呼び出しの行として記録に現れます。

最初から用意されているサブエージェント

Claude Code には、適切な場面で Claude が自動的に使う組み込みのサブエージェントが含まれています。それぞれ親の会話の権限ルールを引き継ぎ、多くは制限されたツールのセットで動きます。Explore と Plan は、調査を速く安く保つため、CLAUDE.md ファイルと git status のスナップショットなしで開始します(公式ヘルプ)。

サブエージェント 使えるツール 目的
Explore 読み取り専用のツール。Write と Edit は拒否される ファイルの発見・コード検索・コードベースの探索
Plan 読み取り専用のツール。Write と Edit は拒否される 計画のためのコードベースの調査
general-purpose サブエージェントが使えるすべてのツール 複雑な調査・複数ステップの操作・コードの変更

Explore を呼び出すとき、Claude は徹底度のレベルを指定します。狙いを定めた確認には quick、バランスを取った探索には medium という使い分けです。組み込みのサブエージェントは、対話型のセッションではデフォルトで登録されます。

エージェントチームとの違い

複数のセッションを協調させるエージェントチームという仕組みもありますが、実験的でデフォルトでは無効です。公式ドキュメントは、チームを組む前に軽い選択肢で足りるかを確認するよう勧めており、サブエージェントは1つのセッションの中で動くと説明しています。サブエージェントは結果を呼び出し元に返し、エージェントチームではチームメイトがタスクリストを共有して互いに直接やり取りします。トークンの費用は、結果を要約して返すサブエージェントのほうが低く、チームメイトごとに別の Claude インスタンスになるチームのほうが高いという比較です。報告を返す素早く焦点の絞られた働き手が欲しいときはサブエージェント、知見を共有して互いに検討し自分たちで調整する必要があるときはエージェントチーム、という使い分けが示されています(公式ヘルプ)。

サブエージェントの作り方と呼び出し方

サブエージェントは YAML frontmatter を付けた Markdown ファイルです。作るには Claude に書いてもらうか、自分でファイルを書きます。公式のクイックスタートは、コードを読んで改善案を出す個人用のサブエージェントを作る流れで説明されています。

定義ファイルを作る手順の図解:作成を頼む(欲しい役割と保存先を伝えてClaudeにファイルを書かせる)、ファイル確認(frontmatterが依頼した内容と合っているかを開いて確かめる)、呼び出す(エージェントの名前を挙げて委任を頼み結果を確認する)

定義ファイルを作る3つの手順

  1. Claude Code の中で、欲しいサブエージェントと保存先を説明して作成を頼みます。Claude は名前、説明、ツールの一覧、モデル、システムプロンプトを含むファイルを書きます。
  2. 書かれたファイル(例では ~/.claude/agents/code-improver.md)を開き、frontmatter が依頼した内容と合っているかを確認します。
  3. 新しいサブエージェントに委任するよう Claude に頼み、動くかを確かめます。

手順1で使う依頼文は、次のような形です。

~/.claude/agents/ に、個人用の code-improver サブエージェントを作ってください。
ファイルを読み、読みやすさ・性能・ベストプラクティスの観点で改善案を出す役割です。
見つけた問題ごとに、問題の説明、現在のコード、改善後のコードの3点を示してください。
読み取り専用にして、モデルは Sonnet を使う設定にしてください。

できあがるファイルは次のような形です。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. For each issue you find, explain
the problem, show the current code, and provide an improved version.

このファイルが ~/.claude/agents/ にあるため、サブエージェントはマシン上のすべてのプロジェクトで使えます。1つのプロジェクトに限定したいときは、そのプロジェクトの .claude/agents/ ディレクトリに移します(公式ヘルプ)。手順3の呼び出しは「code-improver エージェントを使って、このプロジェクトの改善点を挙げてください」のように名前を挙げて頼むだけです。もし Claude が新しいサブエージェントを見つけられないときは、Claude Code を再起動してもう一度試します。

置き場所で変わる使える範囲

定義ファイルの場所が、誰が使えるかを決めます。同じ名前のサブエージェントが複数あるときは、優先順位の高い場所のものが使われます。

置き場所 使える範囲 優先順位 作り方
管理者設定(managed settings) 組織全体 1(最も高い) 管理者設定で配布する
--agents CLI フラグ 現在のセッション 2 起動時に JSON を渡す
.claude/agents/ 現在のプロジェクト 3 Claude に頼む、または手でファイルを作る
~/.claude/agents/ 自分のすべてのプロジェクト 4 Claude に頼む、または手でファイルを作る
プラグインの agents/ ディレクトリ プラグインを有効にした範囲 5(最も低い) プラグインとともに導入する

プロジェクトのサブエージェント(.claude/agents/)は、そのコードベースに固有の担当に向いています。バージョン管理に入れておけば、チームで使いながら改善していけます。ユーザーのサブエージェント(~/.claude/agents/)は、自分のすべてのプロジェクトで使える個人用の担当です。Claude Code は両方を再帰的に走査するので、agents/review/ のようにサブフォルダで整理できます。識別は name フィールドだけで決まるため、サブフォルダの名前は呼び出し方に影響しません。--agents フラグで渡した JSON はそのセッションの間だけ存在し、ディスクには保存されないため、素早い試用や自動化のスクリプトに向くと紹介されています。

frontmatter で設定できること

必須は name と description の2つだけで、残りは任意です。複数語のフィールド名は maxTurns や disallowedTools のように camelCase で書き、表のつづりと完全に一致させる必要があります。認識できないフィールドは、エラーを出さずに無視されます。

項目 必須 書く内容
name 必須 一意の識別子。256文字以内。: は使えない
description 必須 Claude がいつこのサブエージェントに委任すべきか
tools 任意 使えるツール。省略するとサブエージェントが使えるすべてのツールを継承する
disallowedTools 任意 継承または指定したツールの一覧から取り除くツール
model 任意 sonnet, opus, haiku, fable、claude-opus-5-5 のような完全なモデルID、または inherit
permissionMode 任意 default, acceptEdits, auto, dontAsk, bypassPermissions, plan、または default の別名としての manual
maxTurns 任意 サブエージェントが停止するまでの最大のターン数
skills 任意 起動時にサブエージェントのコンテキストへ先読みするスキル
mcpServers 任意 このサブエージェントが使える MCP サーバー
omitClaudeMd 任意 true にすると CLAUDE.md を初期のコンテキストに入れずに開始する
isolation 任意 worktree にすると一時的な git worktree で実行する

description はコンテキストを消費するため短く保つよう案内されています。組み込み以外の description の合計が15,000トークンを超えると、Claude Code は起動時に合計のトークン数とともに警告を表示します。詳しい内容は、そのサブエージェントが動くときにだけ読み込まれるシステムプロンプト側に移します。サブエージェントが受け取るのは、このシステムプロンプトと作業ディレクトリのような基本的な環境の情報で、Claude Code のシステムプロンプトは受け取りません。

作ったあとの確認と更新

Claude Code は ~/.claude/agents/ と .claude/agents/ を監視しています。ファイルを追加・編集すると数秒のうちに変更を検知し、次の委任から更新後の定義が使われ、再起動は要りません。/agents を実行すると、Claude に頼むか2つのディレクトリを直接編集するよう促すリマインダーが表示されます。どのモデルで動いているかを確かめたいときは /tasks を実行すると、その行にモデル名が表示されます。

読み込まれないときの原因は決まっています。name がないファイルは、エージェントの隣に置かれたドキュメントとして扱われます。name があっても description がないファイルはスキップされ、理由がデバッグログに書かれます。YAML が解析できないファイルもフィールドが読まれずスキップされ、解析エラーがログに記録されます。デバッグログを見るには claude --debug を付けて実行し、frontmatter が解析できないファイルを探すには .claude/agents や ~/.claude/agents に対して claude plugin validate を実行します。

1人開発で調べ役とレビュー役を分ける

1人で開発や調査をしていると、仕様を調べる作業と、書いたものを点検する作業が同じ会話に混ざります。公式ドキュメントが挙げる「探索と実装をメインの会話の外に置く」「使えるツールを限定して制約を課す」という2点は、この混ざりをほどくのに向いた性質です。ここからは出典にある機能の範囲で、役割を分ける進め方の例を紹介します。

調べ役とレビュー役の分担の図解:調べ役(tools に Read, Grep, Glob を指定して読み取り中心にする)、レビュー役(問題の説明と現在のコードと改善後のコードを返させる)

調べ役のサブエージェント

調べ役には、読み取り中心のツール構成が合います。クイックスタートの例では tools に Read, Grep, Glob を指定していました。tools を省略するとサブエージェントが使えるすべてのツールを継承するので、調査だけを任せたいなら明示しておく、という考え方です。自分で Explore という名前のユーザーまたはプロジェクトのサブエージェントを定義すると組み込みを上書きし、自分の model フィールドを保つため、model: haiku と書いて探索を低コストのモデルで動かす例が示されています。

調査担当のサブエージェントに、このリポジトリでユーザー認証に関わるファイルを洗い出してもらってください。
前提: 変更はしないでください。読むだけです。
出力の形: ファイルのパス、その役割の1行説明、関連する関数名、の3列の表にしてください。
最後に「次に読むべき3ファイル」を箇条書きで添えてください。

レビュー役のサブエージェント

レビュー役は、出力の形を決めておくと受け取った後の判断が速くなります。クイックスタートの例では、見つけた問題ごとに「問題の説明」「現在のコード」「改善後のコード」を示すようシステムプロンプトで指定していました。レビューの観点は description に短く書き、具体的な手順はシステムプロンプト側に書くと、description が長くなりすぎるのを避けられます。

code-improver エージェントを使って、直近に書いた決済処理のファイルをレビューしてください。
前提: 既存の挙動は変えない方針です。修正は適用せず、提案だけにしてください。
出力の形: 深刻度の高い順に、問題の説明、現在のコード、改善後のコード、の3点を1件ずつ並べてください。

調べ役とレビュー役に別々のモデルを割り当てたいときは、定義の model フィールドを使います。モデルは、Claude が渡せる呼び出しごとのパラメータ、定義の model フィールド、CLAUDE_CODE_SUBAGENT_MODEL 環境変数、メインの会話のモデルという順番で決まります。すべてのサブエージェントを1つのモデルで動かしたい場合は、CLAUDE_CODE_SUBAGENT_MODEL に加えて CLAUDE_CODE_SUBAGENT_MODEL_FORCE を 1 に設定する方法が案内されています。

共通の前提は CLAUDE.md に寄せる

CLAUDE.md は、プロジェクトのルートに置くと Claude Code が毎回のセッションの開始時に読む Markdown ファイルです(公式ヘルプ)。コーディング規約やアーキテクチャの決定、使うライブラリ、レビューのチェックリストを書く場所として紹介されています。役割ごとの指示はサブエージェントのシステムプロンプトに、プロジェクト共通の前提は CLAUDE.md に、と置き場所を分けておくと見通しがよくなります。委任プロンプトだけで足りるサブエージェントには、omitClaudeMd を true にして CLAUDE.md を初期のコンテキストに入れずに開始する設定もあります。

仕事で使うときのコツ

つまずきやすい点の図解:必須項目もれ(nameやdescriptionがないファイルは読み込まれない)、説明が長い(descriptionはコンテキストを使うため短く保つ)、名前の重複(同じディレクトリで同じnameは片方しか読み込まれない)、使用量(サブエージェントのリクエストも同じ使用量上限に入る)

よくある失敗と対策

  • 定義ファイルを置いたのに呼び出せない。name がないファイルはドキュメントとして扱われ、name があっても description がないファイルはスキップされます。まず frontmatter の2項目を確認し、それでも見つからないときは Claude Code を再起動します。
  • description を長く書きすぎる。組み込み以外の合計が15,000トークンを超えると起動時に警告が出るため、詳細はシステムプロンプト側に移すのが公式の案内です。
  • 同じ名前のファイルが散らばる。Claude Code はサブフォルダも再帰的に走査しますが、識別は name だけで決まります。同じ .claude/agents/ の中で同じ name を宣言したファイルが2つあると、片方しか読み込まれません。
  • 使用量の見込みを立てずに並べる。サブエージェントは自分のリクエストを送り、メインの会話と同じ使用量の上限にカウントされます。費用を抑えたい作業は、Haiku のような高速で低コストのモデルに振る選択肢があります。
  • ツールの範囲を決めないまま任せる。tools を省略するとすべてのツールを継承します。調査だけを任せたいなら tools を書くか、disallowedTools で取り除く形が考えられます。

職種別の使い方

ここから挙げるのは機能の仕様ではなく、使い方の例です。

営業の場面では、社内のドキュメントから条件を拾う作業を調べ役に任せ、提案文そのものはメインの会話で詰める分け方が考えられます。MCP(AIツールと外部のデータ源をつなぐオープンな標準)を使えば、Claude Code は自分のツールやデータベース、APIにアクセスできます(公式ヘルプ)。サブエージェントごとに使える MCP サーバーは mcpServers で指定できます。

事務の場面では、同じ指示を何度も貼っているなら定義にしておく、という公式の判断基準がそのまま使えます。手順が長い作業には、指示をまとめた SKILL.md を作るスキルの仕組みもあり、公式ドキュメントはスキルを追加の指示や実行可能なコマンドを与えるもの、サブエージェントを隔離したコンテキストでタスクを実行するものとして並べて紹介しています。

企画の場面では、調査の結果をメインの会話に流し込まずに要約だけ受け取れる点が効きます。論点ごとに description を分けた調べ役を用意し、集まった要約を見ながら自分で判断する、という進め方が例として挙げられます。

企業で使うなら

導入時の注意点

組織で配る場合は、管理者が配布する管理者設定のサブエージェントが使えます。管理者設定ディレクトリの中の .claude/agents/ に、プロジェクトやユーザーのサブエージェントと同じ frontmatter の形式で Markdown ファイルを置く方法で、同じ名前のプロジェクトやユーザーの定義より管理者の定義が優先されます。

権限の扱いも先に決めておくとよいでしょう。組み込みのサブエージェントは親の会話の権限ルールを引き継ぎます。どのサブエージェントにも委任させたくないときは Agent ツール自体を permissions.deny で拒否し、拒否のルールは bypassPermissions を含むすべてのモードでブロックされます(公式ヘルプ)。Manual モード(設定値は default)では、作業ディレクトリ内のファイルの読み取りや、サブエージェントの起動のように承認の要らない操作が確認なしで動きます。データの扱いでは、サブエージェントごとに MCP サーバーを指定できる点と、接続前に各サーバーを信頼できるか確かめるよう案内されている点を押さえます。外部のコンテンツを取得するサーバーはプロンプトインジェクションのリスクにさらされる可能性がある、という注意書きも公式ドキュメントにあります。

判断材料

運用の確認手段としては、サブエージェントが動いている間に /tasks を実行してモデルを確かめる方法、claude --debug を付けてデバッグログを見る方法、.claude/agents や ~/.claude/agents に対して claude plugin validate を実行する方法が案内されています。プロジェクトのサブエージェントはバージョン管理に入れておけば、チームで使いながら改善できます。費用の見積もりでは、サブエージェントが自分のリクエストを送り、メインの会話と同じ使用量の上限にカウントされることが前提になります。料金やプランの条件は変わることがあるため、2026年11月時点の公式ページで、使う前に最新の内容を確かめてください。社内のルール作りや研修まで含めて進めたい場合は、法人向けの支援を使う選択肢もあります。株式会社デジライズは法人向けAIリスキリングサービスで導入社数No.1(東京商工リサーチ・2026年3月末時点)で、累計600社超・5万人以上のAI活用を支援しています。法人での導入や研修を検討するなら株式会社デジライズに相談できます。

よくある質問

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

サブエージェントは自分のリクエストを送り、それはメインの会話と同じ使用量の上限にカウントされます。費用を抑えたい作業には、Haiku のような高速で低コストのモデルにタスクを振る方法が案内されています。定義の model フィールドでモデルを指定できます。

定義ファイルを直したら再起動が必要ですか

Claude Code は ~/.claude/agents/ と .claude/agents/ を監視しており、変更を数秒のうちに検知して、次の委任から更新後の定義を使います。再起動は要りません。

作ったサブエージェントが呼び出せないときは

まず frontmatter を確認します。name がないファイルはドキュメントとして扱われ、name があっても description がないファイルはスキップされて理由がデバッグログに書かれます。デバッグログは claude --debug を付けて実行すると確認できます。それでも Claude が新しいサブエージェントを見つけられないときは、Claude Code を再起動してもう一度試します。

サブエージェントとスキルはどう違いますか

スキルは SKILL.md に指示を書くと Claude が自分の道具立てに加える仕組みで、同じ指示やチェックリスト、複数ステップの手順を繰り返し貼っているときに作るものとして案内されています。公式ドキュメントは、スキルを追加の指示や実行可能なコマンドを与えるもの、サブエージェントを隔離したコンテキストでタスクを実行するものとして並べて紹介しています。

あわせて読みたい

まとめ

  • サブエージェントは特定の種類のタスクを扱う専用のAIアシスタントで、独自のコンテキストウィンドウと専用のシステムプロンプト、特定のツールアクセス、独立した権限を持つ
  • 定義は YAML frontmatter を付けた Markdown ファイルで、必須は name と description の2つだけ
  • ~/.claude/agents/ はすべてのプロジェクト、プロジェクトの .claude/agents/ はそのプロジェクトだけで使える
  • 呼び出しはエージェントの名前を挙げて頼めばよく、タスクが description に一致すれば Claude が委任する
  • 使用量はメインの会話と同じ上限にカウントされるため、モデルの指定とツールの範囲を決めてから任せる

まずは読み取り専用の調べ役を1つだけ作り、同じ調査を頼み直す手間が減るかを確かめてみてください。体系的に学ぶなら、デジライズAIスクールのコース一覧や料金プランから、「5.マルチエージェントと自動化 ~ Claude~」のような講座を合わせて確認するとよいでしょう。

出典


この記事は、各社の公式のヘルプ・ドキュメントや公的機関の資料をもとに AI で下書きし、出典の本文との照合とGoogle 検索による事実確認(ファクトチェック)を通ったものだけを公開しています。料金や機能は変わることがあるため、使う前に公式ページで最新の情報を確かめてください(2026年11月22日時点)。