Claude Codeのサブエージェントを作る方法と使い方を紹介します。Agent Teamsとの違いも説明します。AInformation編集部は同じ課題を1人・サブエージェント・Agent Teamsで3回ずつ試しました。作業にかかった時間とトークン数を比較しました。自作のサブエージェントが呼ばれる条件も紹介します。
Claude Codeのサブエージェントは、メインの会話とは別の窓で仕事を受け持つ助手です。調べものや決まった作業を任せると、結果だけがメインの会話に返ってきます。
AInformation編集部は2026年11月16日に、Claude Code 2.1.325で試しました。2つの課題を3〜4つの進め方で3回ずつ試しました。自作のサブエージェントが呼ばれる条件も30回調べています。
- サブエージェントとAgent Teamsの違い(表)
- サブエージェントの作り方(コピーできるファイルの全文)
- どう頼むと自作のサブエージェントが呼ばれるか(実測)
- Agent Teamsの有効化と使い方
- 同じ課題を1人・サブエージェント・Agent Teamsで比べた時間とトークン
Claude Codeのサブエージェントとは?別の窓で働く助手
サブエージェントは、Claude Codeが仕事の一部を任せる別のClaudeです。自分専用の会話の窓を持ち、終わると要約した結果をメインの会話へ返します。
任せた先で読んだファイルや長い出力は、メインの会話に残りません。そのため長い作業でも、メインの会話の窓が埋まりにくくなります。
最初から入っているサブエージェント
何も作らなくても、Claude Codeにはいくつかのサブエージェントが入っています。Claudeは依頼内容に合わせて、使うサブエージェントを自分で選びます。
最初から入っている主なサブエージェント
| 名前 | すること |
|---|---|
| Explore | コードを探して読むだけ(書き換えない) |
| Plan | プランモードで計画の下調べをする |
| general-purpose | 調べて直す。すべての道具を使える |
| claude-code-guide | Claude Codeの使い方の質問に答える |
ExploreとPlanはファイルを書き換えられません。内容を読む作業だけを担当します。ExploreとPlanはCLAUDE.mdを読まずに始まるので、下調べが軽く済みます。
サブエージェントを使う3つのメリット
- メインの会話が軽く保てる:任せた先の出力は要約だけが戻る
- 道具と許可を絞れる:読むだけの係・テストだけの係を作れる
- 安いモデルに任せられる:決まった作業はHaikuで動かせる
一方でサブエージェントは、任せるたびに別の会話で情報を読み直します。そのためトークン数と時間が増えやすくなります。どれだけ増えたかは、後の節で実測を紹介します。
skillsやCLAUDE.mdとの違い
- skills:手順書。メインの会話の中で読まれる
- サブエージェント:別の窓で動く担当者
- CLAUDE.md:毎回読ませる決まりごと
手順をそろえたいならskills、作業を切り分けて任せたいならサブエージェントが向いています。詳しい手順はskillsの作り方の記事とCLAUDE.mdの書き方の記事で紹介しています。
Agent Teamsとは?サブエージェントとの違い
Agent Teamsは、複数のClaude Codeをチームとして動かす機能です。最初の会話がリード役になり、チームメイトに仕事を割り振ります。
サブエージェントとの一番の違いは、チームメイトどうしが直接話せることです。共有のタスクの一覧を見ながら、空いた仕事を自分で引き受けます。
サブエージェントとAgent Teamsの違い
| 項目 | サブエージェント | Agent Teams |
|---|---|---|
| 始め方 | 最初から使える | 設定で有効にする |
| やり取り | 結果を親に返す | 仲間どうしで話す |
| まとめ役 | メインの会話 | リード(最初の会話) |
| -pで使う | 使える | 立ち上がらない |
| トークン(実測) | 1人の約4.3倍 | 1人の約3.9倍 |
Agent Teamsは試験中の機能で、初期設定では無効です。有効にすると、Claudeが名前を付けて呼んだサブエージェントもチームメイトとして立ち上がります。
Claude Codeのサブエージェントの作り方は?ファイル1枚で作れる
サブエージェントは、Markdownのファイル1枚で作れます。ファイルの冒頭に名前と説明を書きます。その下にサブエージェントへの指示を書きます。
/agentsの画面は使えなくなった
以前は/agentsと打つと作成の画面が開きました。2.1.325で/agentsを入力すると、作成画面は取り除かれたと表示されます。

今はClaudeに頼んで作るか、ファイルを自分で書きます。Web記事で/agentsの画面を使う手順を見かけたら、古い版の説明です。
Claudeに頼んで作る
作りたいサブエージェントをClaudeに説明する方法が一番簡単です。置き場所・使う道具・モデル・呼ばれる場面の4つを入れて頼みます。
data/ のCSVを点検するサブエージェントを .claude/agents/csv-auditor.md に作ってください。
使う道具は Read・Glob・Grep・Bash だけにして、モデルは haiku にしてください。
CSVを見る頼みでは必ずこのサブエージェントを使うように、description を書いてください。
ファイルを自分で書く(全文)
次の内容を.claude/agents/csv-auditor.mdに保存すると、CSVを点検するサブエージェントを作れます。AInformation編集部が呼ばれ方を試したときのファイルです。
---
name: csv-auditor
description: CSVのデータの欠け・重複・形の誤りを調べる専門のエージェント。data/ のCSVを見る・確かめる・調べる頼みでは、自分で読まずに必ずこのエージェントを使うこと(use proactively)。
tools: Read, Glob, Grep, Bash
model: haiku
---あなたはCSVの点検係です。頼まれたCSVをPythonの標準のcsvで読み、次の3つを数えて報告します。
1. 行数と列の名前
2. order_id など1列目の値の重複の数
3. 空の値がある行の数報告の1行目には必ず「監査メモ v1」と書いてください。
保存すると、Claude Codeは数秒で読み込みます。ただしagentsのフォルダを新しく作ったときは、Claude Codeを起動し直してください。
置き場所と使える範囲
置き場所で使える範囲が変わります。同じ名前のサブエージェントが複数ある場合は、表の上にある場所のファイルが優先されます。
サブエージェントのファイルの置き場所
| 置き場所 | 使える範囲 |
|---|---|
| .claude/agents/ | そのプロジェクト(チームで共有) |
| ~/.claude/agents/ | 自分のすべてのプロジェクト |
| プラグインのagents/ | プラグインを入れた所 |
| –agents(JSON) | その起動の間だけ |
チームで同じサブエージェントを使うなら、.claude/agents/に置いてリポジトリに入れます。自分だけで使うなら~/.claude/agents/が便利です。
よく使う設定の項目
必ず書くのはnameとdescriptionの2つだけです。ほかは必要なものだけ足します。
よく使う設定の項目
| 項目 | 書くこと |
|---|---|
| name(必須) | 呼ぶときの名前 |
| description(必須) | どんなときに任せるか |
| tools | 使ってよい道具(書かなければ全部) |
| model | haiku・sonnet・opus・inherit |
| permissionMode | 許可の聞き方 |
| skills | 最初から読ませるskills |
| memory | 会話をまたいで覚える範囲 |
| isolation | worktreeで別の作業場にする |
項目名を間違えてもClaude Codeはエラーを表示せず、その項目を無視します。効いていないと思ったら、まず綴りを見てください。
サブエージェントの使い方は?呼ばれる条件を試した
サブエージェントを呼ぶ方法は4通りあります。Claudeに任せる・名前を出す・@で指名する・会話ごと任せる方法です。
- おまかせ:頼みの中身とdescriptionが合えば、Claudeが自分で選ぶ
- 名前を出す:「csv-auditorサブエージェントを使って」と書く
- @で指名する:
@agent-csv-auditorと書くと必ずそのサブエージェントになる - 会話ごと任せる:
claude --agent csv-auditorで起動する
どう頼むと呼ばれる?30回試した結果
AInformation編集部は、前の節のサブエージェントのdescriptionを2通り用意して試しました。ふつうの説明と「必ず使う」と書き足した説明です。
Sonnet 5.5の-pを使い、5通りの頼み方をそれぞれ3回ずつ試しました。表はサブエージェントが呼ばれた回数です。
自作のサブエージェントが呼ばれた回数
| 頼み方 | ふつうの説明 | 必ず使うと書いた説明 |
|---|---|---|
| 中身に合う頼み | 3/3回 | 3/3回 |
| 名前を出して頼む | 3/3回 | 3/3回 |
| @agent-で指名する | 3/3回 | 3/3回 |
| CSVを見るだけの頼み | 0/3回 | 3/3回 |
| 関係のない頼み | 0/3回 | 0/3回 |
依頼内容が合う・名前を出す・@で指名するの3つは、descriptionの書き方によらず18回中18回呼ばれました。関係のない頼みでは一度も呼ばれていません。
差が出たのは「CSVを見るだけの頼み」です。ふつうの説明では0回で、「必ず使う」と書くと3回呼ばれました。
ただしサブエージェントを呼んだ場合は平均22.3秒でした。Claudeが自分で読んだ場合の8.1秒より時間がかかっています。小さな作業まで任せると、待ち時間が延びます。
バックグラウンドで動くのが標準
対話の画面でClaudeがサブエージェントを呼ぶと、標準ではバックグラウンドで動きます。処理中もメインの会話で次の依頼を入力できます。
動いているサブエージェントは、入力欄の下の一覧に並びます。
- ↑と↓:サブエージェントを選ぶ
- Enter:中身を開いて話しかける
- x:選んだサブエージェントを止める
結果を待ってから進めたいときは、設定のCLAUDE_を0にして起動し直します。そのうえで「終わるまで待って」と頼みます。
Agent Teamsの使い方は?有効にして頼むだけ
Agent Teamsは設定を1行追加し、対話画面で「チームを作って」と頼むと使えます。チームメイトの数や受け持ちも、ふつうの言葉で指示できます。
有効にする設定
設定ファイル(settings.json)のenvに次の1行を足します。ターミナルで環境変数として渡しても同じです。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
チームを作る頼み方
人数と担当する作業を伝えると、Claudeはその内容に合わせてチームを作ります。AInformation編集部が試したときの頼み方です。
TASK.md を読んで、書いてあるとおりにしてください。
エージェントチームを作り、3人のチームメイトに2つずつ分担させてください。
AInformation編集部の検証では、リードがmate-1からmate-3の3人を起動しました。各チームメイトが2つずつ担当しました。入力欄の下に3人の行が並び、それぞれの進み具合とトークンが出ます。

チームメイトの見方と止め方
- ↑と↓:チームメイトを選ぶ
- Enter:そのチームメイトの会話を開き、直接話しかける
- Esc:選ぶのをやめる。会話を開いているときは、その作業を止める
- x:選んだチームメイトを止める
チームメイトを1人ずつ別の画面に表示したいときは、teammateModeをautoにします。tmuxかiTerm2の中で起動すると、チームメイトごとに画面が分かれます。
{
"teammateMode": "auto"
}
-pやスクリプトではチームが立たない
claude -pのような対話のない起動では、Agent Teamsは立ち上がりません。名前を付けたサブエージェントも、ふつうのサブエージェントとして動きます。
AInformation編集部が比較を対話の画面で行ったのは、このためです。定時の処理でチームを使う作りは、今のところできません。
チームの終わらせ方と気をつけること
チームメイトを1人ずつ終わらせるときは、「mate-1に終わるよう伝えて」とリードに頼みます。会話を閉じると、チームの設定は自動で消えます。
- 1つの会話で持てるチームは1つだけ
- チームメイトは自分のチームメイトを作れない
- /resumeで会話を戻しても、チームメイトは戻らない
- 同じファイルを何人もが直すと、上書きし合う
サブエージェントとAgent Teamsはどちらが得?同じ課題で比べた
AInformation編集部は関数を作る課題を4つの進め方で3回ずつ試しました。正しさはすべて満点でした。時間はほぼ変わらず、トークン数だけが大きく増えました。

試した課題と条件
課題は6つの仕様書のとおりに6つの関数を作り、テストを書いて通すものです。仕様には四捨五入のルールや30日目を含むかどうかなど、間違えやすい条件を入れました。
正しさは練習用フォルダに置いていない24個の確認項目で採点しました。モデルはSonnet 5.5、許可は自動モードです。4つの進め方は次のとおりです。
- 1人:サブエージェントを使えない設定にする
- おまかせ:何も指示しない
- サブエージェント:「1つずつ任せて並行で」と頼む
- Agent Teams:有効にして「3人で2つずつ」と頼む
結果:正しさは同じでトークンは約4倍
12回とも24点の満点でした。平均の時間は1人が47.1秒でした。サブエージェントは43.1秒で、Agent Teamsは49.4秒です。
6つの関数を作る課題の結果(3回の平均)
| 進め方 | 時間 | トークン | 正しさ(24点) |
|---|---|---|---|
| 1人 | 47.1秒 | 約22.1万 | 24点 |
| おまかせ | 41.1秒 | 約22万 | 24点 |
| サブエージェント | 43.1秒 | 約94.2万 | 24点 |
| Agent Teams | 49.4秒 | 約86.9万 | 24点 |
トークンはサブエージェントが1人の約4.3倍で、Agent Teamsは約3.9倍でした。任せた先がそれぞれ仕様やファイルを読み直すためです。
公式の文書では、プランモードのチームメイトが通常の約7倍のトークンを使うと説明しています。AInformation編集部の試し(プランモードなし)では約3.9倍でした。
トークンの数には、前の会話の続きとして読み直した分(キャッシュ)も入っています。新しく書いた量(出力)だけで比べても、サブエージェントは約2倍でした。
読む量が多い課題では少し速くなった
1人・おまかせ・サブエージェントの3つでは、別の課題も試しました。6つの社内規程(各約1.4万字)から食い違う条文を探す課題です。読む量が多く、1つずつ切り分けやすい作業です。
読む量が多い課題の結果(3回の平均)
| 進め方 | 時間 | トークン | 見つけた組(12組) |
|---|---|---|---|
| 1人 | 27.4秒 | 約33.4万 | 12組 |
| おまかせ | 25.5秒 | 約33万 | 12組 |
| サブエージェント | 23.2秒 | 約68.5万 | 12組 |
サブエージェントに1つずつ任せると、平均27.4秒が23.2秒になりました。3回の所要時間のばらつきも小さくなりました。代わりにトークンは約2倍に増えました。
頼まないとClaudeは任せなかった
何も指示しない「おまかせ」では、2つの課題で6回ともサブエージェントを使いませんでした。Claudeは、1つの会話で済む大きさなら自分で進めます。
任せたいときは、頼みの中で分け方まで書くのが確実です。AInformation編集部が規程の課題で使った頼み方です。
TASK.md を読んで、書いてあるとおりにしてください。
6つの規程は、サブエージェントに1つずつ任せて並行で読ませてください。
チームメイトどうしは話さなかった
Agent Teamsを使った3回で、チームメイトがリードへ送った連絡は合計3回でした。チームメイトどうしの連絡は0回です。
チームメイトが送った連絡(3回の合計)
| あて先 | 回数 |
|---|---|
| リードへ | 3回 |
| チームメイトどうし | 0回 |
受け持ちがはっきり分かれた作業では、チームもサブエージェントと同じ動きになります。話し合いが要る調べものやレビューでないと、チームの良さは出にくいです。
作業中にチームメイトの1人が「別の人の関数のテストが落ちる」と報告しました。もう1人がまだ作成中だったためです。最後にはすべてのテストが通りました。
どれを使うと得か
時間を縮めたいだけなら、小さな作業を分けても効果は小さいです。サブエージェントは読む量が多い作業や、使える道具を絞りたい作業に向いています。
どれを使うと得か
| こんな作業 | 向いている進め方 |
|---|---|
| 1つの直し・短いやり取り | 1人(メインの会話) |
| 調べものが多く結果だけ欲しい | サブエージェント |
| 道具やモデルを絞りたい | 自作のサブエージェント |
| 分担して互いに確かめたい | Agent Teams |
| 同じファイルを何人もで直す | 1人(チームは向かない) |

サブエージェントのモデルの分け方は?Haikuに任せて節約する
サブエージェントごとにモデルを変えられます。決まった点検や検索はHaikuに任せます。判断が必要な作業では性能の高いモデルを使う分け方です。
ファイルのmodelにhaikuと書くと、メインがSonnetでもサブエージェントはHaikuで動きます。AInformation編集部の試しでも、呼ばれた回はすべてHaiku 5.5で動いていました。
サブエージェントのモデルが決まる順番
| 順番 | どこで決めるか |
|---|---|
| 1 | 呼び出すときにClaudeが渡すモデル |
| 2 | ファイルのmodelの項目 |
| 3 | CLAUDE_CODE_SUBAGENT_MODEL |
| 4 | メインの会話と同じモデル |
すべてのサブエージェントを1つのモデルにそろえたいときは、設定のenvに次の値を足します。強制するときはCLAUDE_も1にします。
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
}
}
Agent Teamsでは、頼みの中で「チームメイトはSonnetで」と書けます。公式の文書も、チームメイトにはSonnetを勧めています。モデルの分業の効果は高いAIと安いAIの分業のニュースでも紹介しています。
サブエージェントやAgent Teamsがうまく動かないときは?
AInformation編集部が検証中につまずいた点と、公式の文書に載っている症状をまとめました。
うまく動かないときの早見表
| 症状 | まず試すこと |
|---|---|
| 自作のサブエージェントが呼ばれない | descriptionに「必ず使う」と書く |
| /agentsで作れない | ファイルを書くかClaudeに頼む |
| チームが立たない | 設定と対話の画面かを確かめる |
| 頼んでいないのにチームになる | Agent Teamsの設定を0にする |
| 許可の確認が何度も出る | 先に許可のルールを足す |
| トークンが増えすぎる | 人数を減らしHaikuに任せる |
自作のサブエージェントが呼ばれない
まずdescriptionを見直します。「見るだけ」の頼みでは、ふつうのdescriptionだと呼び出しは0回でした。「必ず使う」と書くと3回呼ばれています。
data/ のCSVを見る・確かめる・調べる頼みでは、自分で読まずに必ずこのエージェントを使うこと(use proactively)。
確実に使わせたいときは、@agent-の後ろに名前を付けて指名します。新しくagentsのフォルダを作ったときは、起動し直さないと読まれません。
頼んでいないのにチームが立つ
Agent Teamsを有効にしていると、Claudeが名前を付けたサブエージェントはチームメイトになります。チームが要らない作業では、CLAUDE_を0にします。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
}
}
許可の確認が何度も出る
チームメイトやバックグラウンドのサブエージェントが操作の許可を求めると、確認画面がメインの画面にまとめて表示されます。よく使う操作は、先に許可のルールへ足しておくと止まりにくくなります。
AInformation編集部の試しでも、読むだけのコマンドで最初の確認が出ました。許可の決め方はClaude Codeの許可とセキュリティの記事で紹介しています。
まとめ
- サブエージェントは別の窓で働く助手で、ファイル1枚で作れる。2.1.325では/agentsの作成画面がなくなった
- 自作のサブエージェントは、descriptionに「必ず使う」と書くと見るだけの頼みでも呼ばれた
- Agent Teamsは設定で有効にし、対話の画面で「チームを作って」と頼む。-pでは立たない
- 同じ課題で正しさは変わらず、トークンはサブエージェントで約4.3倍・チームで約3.9倍に増えた
- 読む量が多い作業だけ、サブエージェントで少し速くなった
まずは1人で作業を進めます。読む量が多い作業や使える道具を絞りたい作業だけ、サブエージェントに任せてみてください。Agent Teamsは、話し合いが要る調べものやレビューで試してください。
目的別に読むClaude Codeの記事
- Claude Codeの入れ方と使い方:Claude Codeの使い方の記事
- 料金とプランの違い:Claude Codeの料金の記事
- skillsを作る:skillsの作り方の記事
- hooksで決まった処理を動かす:hooksの記事
- プラグインでまとめて入れる:Claude Codeのプラグインの記事
- CLAUDE.mdを書く:CLAUDE.mdの書き方の記事
- 複数のAIが並列でコードを書く仕組み:複数のAIが並列でコードを書くニュース
- AIコーディングの道具を比べる:AIコーディングナビ
よくある質問
- Claude Codeのサブエージェントとは何ですか?
- Claude Codeが仕事の一部を任せる別のClaudeです。自分専用の会話の窓で動き、終わると結果の要約だけをメインの会話に返します。
- Agent Teamsとサブエージェントの違いは何ですか?
- サブエージェントは結果を親に返すだけです。Agent Teamsはチームメイトどうしが直接話し、共有のタスクの一覧で仕事を分けます。Agent Teamsは設定で有効にする必要があります。
- Agent Teamsを有効にするにはどうしますか?
- settings.jsonのenvに
CLAUDE_を1で足します。そのあと対話の画面で「チームを作って分担して」と頼みます。CODE_ EXPERIMENTAL_ AGENT_ TEAMS - サブエージェントを使うと速くなりますか?
- 作業によります。AInformation編集部の試しでは、6つの関数を作る課題はほぼ変わりませんでした。読む量が多い課題では平均27.4秒が23.2秒になりました。
- Agent Teamsはトークンをどれくらい使いますか?
- AInformation編集部の試しでは、1人で進めたときの約3.9倍でした。チームメイトごとに窓を持つため、人数に比例して増えます。公式の文書は、プランモードなら約7倍としています。
- /agentsコマンドが使えません。
- 2.1.325では、/agentsの作成画面は取り除かれています。Claudeに「サブエージェントを作って」と頼むか、.claude/agents/にファイルを書いてください。
- 自作のサブエージェントが呼ばれないのはなぜですか?
- descriptionが頼みと合っていないことが多いです。「必ず使う」と書き足すか、
@agent-に名前を付けて指名すると呼ばれます。agentsフォルダを新しく作った場合は、Claude Codeを起動し直す必要があります。 - サブエージェントのモデルは変えられますか?
- 変えられます。ファイルのmodelにhaikuやsonnetと書きます。AInformation編集部の試しでは、メインがSonnet 5.5でもサブエージェントはHaiku 5.5で動きました。
- claude -pでもAgent Teamsは使えますか?
- 使えません。-pのような対話のない起動では、チームメイトは立ち上がりません。名前を付けたサブエージェントは、ふつうのサブエージェントとして動きます。
- サブエージェントは何体まで同時に動かせますか?
- 標準では、同時に動けるのは20体までです。入れ子は3段までです。どちらの上限も環境変数で変更できます。
