【Claude Code】サブエージェントの作り方と使い方

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

サブエージェントは、ひとことで言うと特定の仕事を任せられる「別の作業者」です。

メインの会話とは完全に別のコンテキスト（作業スペース）で動き、終わったら結果の要約だけを持ち帰るのが最大の特徴です。調査で読んだ大量のファイルの中身はサブエージェント側に残り、メインの会話には要約しか届かないので、会話が重くならずに済みます。

サブエージェントを自作すると、次のようなことができます。

ちなみにClaude Codeには、コードベース調査用のExploreや計画用のPlanなど、組み込みのサブエージェントが最初から入っています。この記事で作るのは、それらと同じ仕組みで動く「自分専用のカスタムサブエージェント」です。

サブエージェントの作り方｜最小構成を5分で動かす

まずは動くものを作ってみましょう。サブエージェントは、agentsフォルダにMarkdownファイルを1枚置くだけで完成します。題材は「コードレビュー担当」のサブエージェントです。

なお、以前は/agentsコマンドで対話式の作成画面を開けましたが、2026年7月時点の最新版ではこのウィザードは廃止されています。現在はファイルを直接作るか、Claudeに「こういうサブエージェントを作って」と依頼するのが公式の案内する作り方です。ここでは仕組みを理解するために、手動で作ってみます。

1. agentsフォルダを作る

   ターミナルで次のコマンドを実行します（エクスプローラーやFinderで直接フォルダを作ってもかまいません）。~/.claude/agents/に置いたサブエージェントは、自分のPCのすべてのプロジェクトで使えます。

   ターミナル

   Copy

   mkdir -p ~/.claude/agents

2. 定義ファイル（reviewer.md）を書く

   作ったフォルダの中に、Markdownファイルを1枚作ります。全体の構成はこうなります。

   ホームディレクトリ
   └── .claude/
       └── agents/              ← 手順1で作ったフォルダ
           └── reviewer.md      ← このファイルを作る
   

   ---で挟んだ部分（フロントマター）に設定を書き、その下にサブエージェントへの指示（システムプロンプト）を書きます。

   reviewer.md

   Copy

   ---

   name: reviewer

   description: コードを読んで改善点を提案する。コードレビューを頼まれたときに使う。

   tools: Read, Grep, Glob

   model: sonnet

   ---

    

   あなたはコードレビューの専門家です。

   指摘は問題点ごとに、次の3点をセットで示してください。

   - 何が問題か

   - 現在のコード

   - 改善したコード

   ファイル名は自由です。サブエージェントの識別にはファイル名ではなくフロントマターのnameが使われます（迷ったらnameと同じにしておくと管理しやすいです）。

3. 動作確認する

   Claude Codeで、名前を挙げて次のように頼んでみてください。

   reviewerサブエージェントを使って、直近の変更をレビューして
   

   Claudeがreviewerに作業を振り、レビュー結果の要約が返ってきたら成功です。名前を挙げなくても、依頼の内容がdescriptionに合っていれば自動で任されます。

これだけで完成です。定義ファイルの追加・編集はセッション中に自動で反映されるので、基本的に再起動は不要です。ただし、~/.claude/agents/フォルダ自体をセッション中に初めて作った場合だけは、Claude Codeの再起動が必要です（新しいフォルダの監視が再起動時に始まるため）。

定義ファイルの書き方（フロントマターの設定項目）

最小構成が動いたら、次は定義ファイルの中身を整えていきます。フロントマターで必須なのはnameとdescriptionの2つだけで、あとはすべて省略可能です。

自動で任されるかはdescriptionで決まる

Claudeは依頼を受けるたびに、各サブエージェントのdescriptionと依頼内容を照らし合わせて「この仕事を任せるか」を判断しています。つまり、サブエージェントに自動で仕事が振られるかどうかは、descriptionの書き方でほぼ決まります。

コツは、「何をするか」と「いつ任せてほしいか」の両方を書くことです。ユーザーが実際に言いそうな言葉（レビュー・デバッグなど）を入れておくと、依頼と照合されやすくなります。

NG: コードの品質をチェックする。
    →「何をするか」だけで、いつ任せるかが分からない

OK: コードを読んで改善点を提案する。コードレビューを頼まれたときに使う。
    →「いつ任せるか」＋依頼に出てくる言葉（コードレビュー）が入っている

頼まれなくても積極的に使ってほしい場合は、「コードを変更したら毎回使う（use proactively）」のような一文をdescriptionに足す方法が公式ドキュメントで紹介されています。

本文はサブエージェントへの「システムプロンプト」

フロントマターの下の本文は、サブエージェントのシステムプロンプトになります。サブエージェントは通常のClaude Codeのシステムプロンプトを受け取らず、ここに書いた内容が行動の基準のすべてになります。役割（あなたは◯◯の専門家です）・作業手順・出力形式の3点を書いておくと、結果が安定します。

よく使うフロントマターの項目

name・description以外でよく使う項目をまとめます。

tools

使えるツールの許可リスト。省略するとメインの会話と同じツールをすべて継承する
例：tools: Read, Grep, Glob（読み取り専用になる）

disallowedTools

禁止するツールのリスト。書き込みだけ禁止して、残りのツールはそのまま使わせたいときに向いている
例：disallowedTools: Write, Edit

model

使うモデル。sonnet・opus・haikuなどを指定できる。省略するとメインの会話と同じモデルで動く。軽い作業ならhaikuにすると料金を抑えられる

permissionMode

権限確認のモード。plan（読み取り専用の調査モード）やacceptEdits（ファイル編集を自動承認）などを指定できる

memory

永続メモリの置き場所（user／project／local）。指定すると、セッションをまたいで学んだことを書きためる専用フォルダを持てる

skills

起動時に読み込ませるスキル名のリスト。指定したスキルの中身がまるごとサブエージェントに渡される

最初のうちはtoolsとmodelだけ覚えておけば十分です。とくにレビューや調査など「読むだけ」の役割には、この例のようにtools: Read, Grep, Globを指定して書き込みできない状態にしておくのがおすすめです。誤ってファイルを変更される心配がなくなります。

定義ファイルの置き場所は2種類

定義ファイルをどこに置くかで、使える範囲が変わります。

プロジェクト側の.claude/agents/はGitでコミットできるので、チーム全員で同じサブエージェントを共有できます。同じnameのサブエージェントが両方にある場合は、プロジェクト側が優先されます。

このほか、組織全体に配布する管理者用の置き場所や、起動時にJSONで渡す--agentsフラグ、プラグインに同梱する形式もありますが、個人で使うぶんには、ユーザー用（~/.claude/agents/）とプロジェクト用（.claude/agents/）の2つを覚えておけば十分です。

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

作ったサブエージェントは、次の3通りの方法で呼び出せます。

名前を指定する方法は、最終的に任せるかどうかをClaudeが判断します。「確実にこのエージェントで実行したい」場面では@メンションを使ってください。

実際に入力欄で@revまで入力すると、次のように候補が絞り込まれて、作ったreviewerがdescription付きで表示されます。

一覧にはサブエージェントだけでなく、ファイル参照の候補（reviewer.mdなど）も混ざって表示されます。エージェントとして呼び出せるのは、descriptionが表示されている先頭のほうです。

また、2026年7月時点の最新版では、サブエージェントは基本的にバックグラウンドで並行実行されます。サブエージェント側で許可が必要な操作が発生した場合は、メインの会話に確認が表示されるので、そこで承認するかどうかを選べます。

動かない・呼ばれないときのチェックリスト

つまずきやすいポイントと対処法を、よくあるケース別にまとめます。

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

自動で任されない

期待した動きをしない

よくある質問

Q. /agentsコマンドでは作れなくなった？

A. 以前は/agentsで対話式の作成・管理画面を開けましたが、2026年7月時点の最新版ではウィザードは廃止されています。現在/agentsを実行すると、Claudeに作成を依頼するか.claude/agents/を直接編集するよう案内されます。定義ファイルの形式や置き場所は変わっていないので、過去に作ったサブエージェントはそのまま動きます。

Q. サブエージェントはメインの会話の内容を知っている？

A. 知りません。サブエージェントが受け取るのは、定義ファイルのシステムプロンプトと、Claudeが作る依頼文（タスクの要約）です。CLAUDE.mdは読み込まれますが、それまでの会話の流れは引き継がれません。「このファイルは触らないで」のような前提条件がある場合は、依頼するときに明示的に伝えてください。

Q. トークン消費（料金）は増える？

A. 増えやすいです。サブエージェントは毎回まっさらな状態から起動し、CLAUDE.mdの読み込みやプロジェクトの把握をやり直すためです。そのぶんメインの会話には要約しか残らないので、長いセッションではかえって効率が良くなる場合もあります。軽い作業はメインの会話で済ませ、重い調査やレビューに絞って任せると効果を実感しやすいです。

Q. サブエージェントとSkills（スキル）は何が違う？

A. スキルは「手順書」で、メインの会話の中に読み込まれてClaude自身が従います。サブエージェントは「別の作業者」で、独立したコンテキストで作業して要約だけを持ち帰ります。詳しい比較と使い分けは、導入で紹介した記事で解説しています。

まとめ

Claude Codeのサブエージェントの作り方を解説しました。

まずは今回のreviewerのような読み取り専用のエージェントを1つ作って、レビューや調査を任せるところから始めてみてください。細かい仕様は更新されることがあるので、最新の情報は以下の公式ドキュメントで確認してください。

• カスタムサブエージェントの作成 - Claude Code 公式ドキュメント

「毎回守ってほしい手順」を覚えさせたい場合は、サブエージェントよりSkills（スキル）が向いています。スキルの作り方は以下の記事で解説しています。