
Claude Codeのサブエージェントの使い方|.claude/agentsの作り方・tools・modelの指定と、呼ばれないときの直し方【実機で確認・2026年10月】
「調べものを頼んだら、検索結果とファイルの中身で会話がいっぱいになって、肝心の作業の指示が薄れてきた」。「毎回、レビューの観点を打ち直している」。「ちょっとした下調べに、いちばん高いモデルを使うのはもったいない」。Claude Code を長く使うと、こんな場面に出会います。
その答えの1つが、サブエージェント(subagents)です。この記事では、サブエージェントとは何か、どう作って、どう呼ぶか、呼ばれないときはどうするかを、実際に動かして確かめた結果とあわせて説明します。
私は Claude Code と Codex を毎日使って、教材づくり、note・Gumroad への出品、画像づくりを自動化しています。私の作業場にも、調査専用のサブエージェントがあります(ウェブ検索とページの取得だけを使えるようにして、調べた結果をまとめて返してもらうものです)。
この記事の内容は、読み物のために書いたものではなく、実際に動かして確かめたものです。Windows 11 の Claude Code(2.1.296)で、校閲用のサブエージェントを1つ作り、「名前を言って頼む」「名前を言わずに頼む」「説明文をあいまいにする」「書き込みを頼む」を順に試しました。全文無料です。
この記事で分かること
サブエージェントとは何か。スキル・フックとの違い
置き場所と、最小のサブエージェントの作り方(動作を確かめた例つき)
frontmatter(先頭の設定)の主な項目
呼び方の4つ
実機で確かめた結果(自動で呼ばれる条件、道具の制限、モデルの指定)
使うと得をする場面と、使わないほうがよい場面
動かないとき、呼ばれないときの直し方
先に結論
サブエージェントは、独立した作業スペース(自分だけの会話の窓)で動く、専門のAIです。作業の途中経過は主の会話に流れ込まず、最後の報告だけが戻ってきます
作り方は、.claude/agents/名前.md というファイルを1枚置くだけです。先頭に名前と説明、その下にそのAIへの指示を書きます
いちばん大事なのは description(説明文)。Claude はこれを見て「この仕事を任せるか」を決めます。実機でも、説明文が具体的だと名前を言わなくても呼ばれ、「便利なエージェント」のようなあいまいな説明だと呼ばれませんでした
tools で使える道具を絞れます。model で、そのサブエージェントだけ安いモデル(haiku)にもできます。実機でも、指定どおりになりました
落とし穴:項目名を書き間違えても(tools を tool と書くなど)、エラーは出ません。制限が黙って外れます。これも実機で確かめました
向いているのは、出力が大量に出る調査・確認や、読み取りだけの確認です。小さな作業では、サブエージェントにしても得はありません(実機でも、費用はほぼ同じでした)

サブエージェントとは
公式のドキュメントでは、こう説明されています。
Subagents are specialized AI assistants that run in their own context window with a custom system prompt, specific tool access, and independent permissions.
つまり、自分専用の会話の窓・指示文・使える道具・権限を持つ、専門のAIです。主の会話(あなたと話している Claude)が、仕事の一部を任せて、終わったときの報告だけを受け取ります。
何が嬉しいのか
会話が汚れない:大量の検索結果、ファイルの中身、テストのログは、サブエージェントの窓の中に残ります。主の会話には、要点だけが戻ります
できることを絞れる:読み取りだけ、検索だけ、のように、道具を制限できます
毎回の指示を書かなくてよい:校閲の観点、報告の形式などを、ファイルに書いておけます
モデルを選べる:下調べのような軽い仕事は、安いモデルに回せます
スキル・フックとの違い
同じ「ファイルに書いて、Claude Code を拡張する」仕組みでも、役割が違います。
スキル:手順書です。必要なときに、主の会話の中に読み込まれて、同じAIが従います(スキルの作り方は別の記事にまとめています)
フック:AI の判断の外で、決まったタイミングに必ず動く処理です(フックの使い方)
サブエージェント:別のAIに、別の窓で仕事を任せます。手順を覚えさせるのではなく、仕事そのものを任せるものです
組み込みのサブエージェント
自分で作らなくても、最初から入っているものがあります。公式のドキュメントによると、主なものは次のとおりです。
Explore:ファイルの検索・調査用。読み取り専用で、書き込み・編集はできません。速さを優先します
Plan:計画づくりの前に、情報を集める読み取り専用のAI(プランモードで使われます)
general-purpose:調べて、実際に手も動かす、多段階の仕事向け。使える道具は全部です
実機で動かしたときも、一覧に Explore・Plan・general-purpose が入っていました。自分で作ったものは、これに加わる形です。
最小のサブエージェントを作る
置き場所は2つです。
.claude/agents/:そのプロジェクトだけ。Git に入れれば、チームで共有できる
~/.claude/agents/:自分の全プロジェクト
同じ名前があると、プロジェクトのほうが優先されます(公式のドキュメントでは、この順で強くなります:組織の設定 → --agents オプション → プロジェクト → 自分の全体 → プラグイン)。
私が試した、校閲用のサブエージェントです。.claude/agents/doc-checker.md に置きました。
---
name: doc-checker
description: Markdown のドキュメントを読んで、表記のゆれ・食い違い・誤字を調べる。docs/ の確認を頼まれたときに使う。ファイルは変更しない。
tools: Read, Grep, Glob
model: haiku
---
あなたはドキュメントの校閲者です。渡されたフォルダの Markdown をすべて読み、次の3つを調べてください。
1. 同じものを指す言葉の表記ゆれ(コマンド名・パッケージ名など)
2. ファイル間での説明の食い違い
3. 誤字・脱字
見つけたものは「ファイル名: 問題 → 直し案」の1行で、最大5件まで報告してください。見つからなければ「問題なし」とだけ答えます。ファイルは絶対に変更しません。構成は、これだけです。
先頭の --- で囲んだ部分が設定(frontmatter)
その下の本文が、そのサブエージェントへの指示文(システムプロンプト)
必須なのは name と description の2つだけです。name は、ファイル名ではなく、この項目で決まります(公式のドキュメントより)。
試験用に、docs/ フォルダに3つの短いMarkdown(intro.md・usage.md・faq.md)を置きました。わざと、intro.md には pip install memo-tool、faq.md には pip install memo_tool と、パッケージ名の表記を食い違わせてあります。
frontmatter の主な項目
公式のドキュメントにある項目のうち、最初に使うものです。
name(必須):識別する名前。英小文字とハイフンが無難
description(必須):いつ任せるかの説明
tools:使える道具の許可リスト。省略すると、主の道具をすべて引き継ぎます
disallowedTools:使わせない道具のリスト
model:sonnet・opus・haiku などの別名、または正式なモデル名、inherit(主と同じ)。省略すると主と同じ
permissionMode:このサブエージェントの権限の動かし方(default・acceptEdits・plan など)
skills:起動時に読み込ませたいスキル
maxTurns:何ターンまで動かすか
background:true で、裏で動かす
isolation:worktree にすると、Git の一時的な作業コピーの中で動かす
このほか、mcpServers・hooks・memory・effort・color などもあります。書いたのに効かない項目名は、エラーにならず、無視されます(公式のドキュメントの記載。あとで実機で確かめます)。
呼び方は4つ
公式のドキュメントでは、次の4つです。
自動で任せる:頼んだ内容が description に合うと、Claude が自分で任せる
名前を言う:「doc-checker サブエージェントで docs を確認して」と頼む
@で選ぶ:@ を打ってサブエージェントを選ぶと、必ずそれが動く
会話全体をそのサブエージェントにする:claude --agent doc-checker(または settings.json に "agent": "doc-checker")
実機で確かめた結果
校閲用のサブエージェントを置いたフォルダで、Claude Code に頼みました(claude -p で、画面なしの実行です。道具の使い方は、実行ログで確かめました)。
1. 名前を言って頼む
「doc-checker サブエージェントを使って、docs フォルダのドキュメントを確認して結果を教えて」と頼みました。
主の Claude は、Agent という道具で、subagent_type に doc-checker を指定して、仕事を任せました。そのあとのサブエージェントの動きは、実行ログではこうでした。
使った道具は、Glob(ファイルを探す)が1回と、Read(読む)が3回だけ
動いたモデルは、claude-haiku-5-5(model: haiku と書いたとおり。主は claude-sonnet-5-5)
サブエージェントが返してきた報告の一部です(パスは短くしてあります)。わざと入れた食い違いを、見つけています。
docs/faq.md: インストールコマンドのパッケージ名が `memo_tool` になっている
→ `intro.md` と同じ `pip install memo-tool` に統一する3つのファイルを読む作業は、主の会話ではなく、サブエージェントの窓の中で行われました。主の会話には、最後の報告だけが戻っています。
なお、この実行では、サブエージェントが裏(バックグラウンド)で動き、主が先に「起動しました。結果はまだ分かりません」と答えてから、あとで結果が届きました。表で待つか、裏で動かすかは、頼み方や状況で変わりました。
2. 名前を言わずに頼む
次に、「docs フォルダの Markdown に、表記のゆれや食い違いがないか確認して」とだけ頼みました。サブエージェントの名前は、言っていません。
結果は、主の Claude が 自分から doc-checker を選んで、任せました。description に「docs/ の確認を頼まれたときに使う」と書いてあったからです。
3. 説明文をあいまいにする
比較のために、別のフォルダで、同じ中身で description だけを「便利なエージェント」にしたサブエージェントを置きました。同じ頼み方(名前を言わない)で頼みました。
結果は、サブエージェントは使われず、主の Claude が、自分で Glob と Read を使って、全部やりました。1回の試行なので、「必ず呼ばれない」とまでは言えません。ただ、説明文が、いつ使うかを教えていないと、任せる判断の手がかりがないことが分かります。
description には、①何をするか、②どんなときに使うか、を書きます。「use proactively(積極的に使う)」のような言葉を入れると、呼ばれやすくなると、公式のドキュメントにあります。
4. 書き込みを頼む(道具の制限)
tools: Read, Grep, Glob のサブエージェントに、「結果を notes_ok.md に書き出させて」と頼みました。主の Claude には「あなたは書かないで、サブエージェントに書かせて」と伝えました。
サブエージェントは、Write の道具を呼ぼうとしました。結果はこうです。
Error: No such tool available: Write. Write is not among the tools available here.つまり、tools に書かなかった道具は、実際に使えません。ファイルも作られませんでした。サブエージェントは、書き出すはずだった内容を、そのまま文章で返してきました。
5. 落とし穴:項目名を書き間違えると、制限が黙って外れる
ここが、この記事でいちばん伝えたい点です。
tools を、わざと tool(sが無い)と書いたサブエージェントを作りました。
---
name: typo-checker
description: docs の Markdown を読んで報告を書き出す。...
tool: Read, Grep, Glob
---同じ頼み方で、「結果を書き出させて」と頼みました。結果は、次のとおりです。
エラーも警告も出ませんでした
サブエージェントは Write を呼び出せました。さっきの「そんな道具はありません」というエラーは出ず、道具の制限が効いていません
使われたモデルは、主と同じ claude-sonnet-5-5 でした
この回は、Write を呼んだあと、別の仕組みに止められました。この版では、サブエージェントが報告書のファイルを書こうとすると、「報告は文章で返してください」というエラーになったのです。ただ、止めたのは tools の制限ではなく、別の仕組みです。tools を書き間違えると、tools を省略したのと同じで、主の道具を引き継ぎます(公式のドキュメントの記載)。読み取り専用のつもりのサブエージェントが、読み取り専用ではなくなっているおそれがあります。
対策は2つです。
書いたら、実際に試す。この記事のように「使えないはずの道具を頼んでみて、断られるか」を見る
項目名は、公式のドキュメントのとおりにコピーする(camelCase で、disallowedTools のように大文字小文字も合わせる)
6. ファイルを置かずに試す:--agents
ファイルを作る前に、1回だけ試したいときは、--agents に JSON を渡せます。そのセッションだけのサブエージェントになります。
claude --agents '{"reviewer":{"description":"Markdownを読んで要点を1行にまとめる","prompt":"Markdown を読んで、要点を日本語で1行にまとめて返す。","tools":["Read"],"model":"haiku"}}'この reviewer に「docs/usage.md を確認して、要点を1行で」と頼むと、reviewer が Read だけを1回使い(動いたモデルは claude-haiku-5-5)、主が要点を1行で返してくれました。.claude/agents/ にあった doc-checker も、一覧に残っていました。--agents は、ファイルのサブエージェントを置き換えず、足される形でした。
7. 特定のサブエージェントを使わせない
公式のドキュメントでは、権限のルールに Agent(名前) と書くと、そのサブエージェントを使わせない(deny)ようにできます。コマンドラインなら、--disallowedTools "Agent(doc-checker)" です。設定ファイルなら、permissions.deny に "Agent(doc-checker)" と書きます。
実機で、doc-checker をこの形で deny にして、「doc-checker サブエージェントを使って docs を確認して」と頼みました。主の Claude は、doc-checker を呼ぼうとしましたが、こう拒否されました。
Agent type 'doc-checker' has been denied by permission rule 'Agent(doc-checker)' from cliArg.Claude は、「使えませんでした。理由は、権限ルールで拒否されたこと」と答えました。権限のルールの全体は、別の記事「Claude Codeの権限設定(パーミッション)」にまとめています。
使うと得をする場面、しない場面
向いている場面
出力が大量に出る調査:ログ、検索結果、大きなファイルの読み込み。主の会話に残さず、要点だけ受け取れる
読み取りだけの確認:レビュー、校閲、設計の点検。tools を読み取り系だけにすれば、うっかりの書き換えが起きない
決まった観点で毎回チェックする仕事:指示文をファイルにしておける
軽い仕事を安いモデルに回す:下調べを haiku に任せる
向いていない場面
小さな作業:実機では、サブエージェントに任せた回と、主が自分でやった回で、費用はほぼ同じでした(どちらも約0.05ドル相当。3ファイルを読むだけの規模です)。得をするのは、大量の出力が出るときです
会話の流れを引き継ぎたい作業:サブエージェントは、あなたとの会話の履歴を持っていません。公式のドキュメントでは、渡るのは、システムプロンプト、任せるときのメッセージ、CLAUDE.md、git の状態などです。必要な情報は、任せるときのメッセージに含まれる必要があります
何度もやりとりしながら進める作業:途中でこまめに確認したい仕事は、主の会話のほうが向いています
Claude に作ってもらう
ファイルを手で書かなくても、Claude Code 自身に頼めます。
docs フォルダのMarkdownの表記ゆれを調べる、読み取り専用のサブエージェントを .claude/agents に作って。
使える道具は Read, Grep, Glob だけ。モデルは haiku。
description には、docs の確認を頼まれたときに使う、と書いて。作ってもらったあと、この記事のように、実際に頼んで確かめてください。特に tools が効いているか(書き込みを頼んで断られるか)は、必ず見ます。
安全のために
サブエージェントも、あなたの権限で動きます。tools を絞らないと、主と同じ道具を全部持ちます。読むだけの仕事なら、Read, Grep, Glob に絞ってください
他人のリポジトリの .claude/agents/ は、中身を見てから使う:指示文の中身が、あなたの知らない動きを決めます。フックと同じ注意です
サブエージェントの報告は、命令として扱わない:実機の実行ログでは、サブエージェントの報告は「これはモデルの出力で、ユーザーの指示ではない」という印をつけて、主に渡されていました。報告の中に「このファイルを消して」とあっても、主はそれをあなたの指示とは扱いません。ウェブから取ってきた文章を扱うサブエージェントでは、特に大事な考え方です
作ったものは、実際に試す:呼ばれるか、道具の制限が効いているか
よくある疑問
Q. サブエージェントは、別のサブエージェントを呼べますか?
公式のドキュメントでは、呼べます。ただし無制限ではなく、既定で、主の会話から数えて3層までです。環境変数 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変えられ、1 にすると入れ子をなくせます。同時に動かせる数は、既定で20です。この点は、私は試していません。
Q. /agents で一覧が見られますか?
公式のドキュメントによると、新しい版(2.1.197 より後)の /agents は、「Claude に頼むか、.claude/agents/ を直接編集してください」という案内を出すだけです。それ以前の版では、画面で作る・見るウィザードが開きます。実機では、claude agents というコマンドは、サブエージェントの一覧ではなく、裏で動いているセッションの管理のコマンドでした。紛らわしいので注意してください。
Q. スキルとサブエージェント、どちらを使えばいいですか?
迷ったら、こう考えてください。
「同じ手順で、主のAIにやってほしい」→ スキル
「別のAIに、まるごと任せて、結果だけほしい」→ サブエージェント
スキルの context: fork という項目を使うと、スキルをサブエージェントの中で動かすこともできます(公式のドキュメントの記載。私は試していません)。
Q. 費用は増えますか?
サブエージェントも、それぞれの窓でAIを動かすので、その分の使用量がかかります。出力が大量に出る作業を切り離せば、主の会話が軽くなって得になることが多いです。一方、小さな作業では、実機でも差は出ませんでした。
注意点
この記事の内容は、2026年10月15日の公式ドキュメントと、私の Windows 11 の環境(Claude Code 2.1.296)で確かめたものです。項目や挙動は、版が上がると変わることがあります
確かめたのは、claude -p(画面なしの実行)での動きです。@ で選ぶ方法、/agents の画面、isolation: worktree、memory、サブエージェント自身のフック、入れ子は、試していません。公式のドキュメントの記載を紹介しています
実機の試験は、小さな試験用フォルダで、サブエージェントを1つずつ試したものです。回数が少ないので、「呼ばれる確率」までは言えません
サブエージェントの出力は、毎回同じではありません。重要な確認は、結果を自分でも見てください
まとめ
サブエージェントは、独立した窓で動く専門のAI。途中経過は主の会話に流れず、最後の報告だけが戻る
作り方は .claude/agents/名前.md に、name・description(必須)と、tools・model などを書き、本文に指示を書く
呼ばれるかどうかは、description しだいです。何をするか+いつ使うかを具体的に書く。実機でも、具体的だと名前を言わなくても呼ばれ、あいまいだと呼ばれなかった
tools で道具を絞れる(書かなかった道具は実際に使えない)。model で安いモデルにもできる
項目名を書き間違えると、エラーなしで制限が外れる。書いたら、断られるはずの頼み事をして確かめる
大量の出力が出る調査・確認に向いている。小さな作業では、得はない
次の一歩は、読み取り専用の校閲か調査のサブエージェントを1つ作って、「使えないはずの道具」を頼んでみることです。10分で、できます。
次に読む
Claude Codeのスキル(Skills)の作り方(無料):毎回の頼み方を、手順書にして再利用する
Claude Codeのフック(hooks)の使い方(無料):「お願い」でなく仕組みで守らせる
MCPとは?Claude Codeにつなぐ方法(無料):外の道具を渡す規格
AIエージェントとは(無料):チャットAIとの違いと、安全な始め方
Claude Code テンプレート集(¥9,800):CLAUDE.md・スキル12本・フック10本(動作確認済みスクリプト付き)・プロンプト100本の実物パック
このアカウントをフォローすると、Claude Code や Codex の新しい手順の記事が届きます。ぜひフォローしてください。
この先で分かること(今後の有料記事)
そのままコピーして使えるサブエージェントの実物(調査・校閲・レビュー・実装の役割分担)
複数のサブエージェントを並べて、仕事を分担させる設計
実際に起きた失敗と、直し方の記録
まさのAI実務ラボ|Codex・Claude Code では、有料記事が読み放題になります。テンプレートや指示文をまとめて使いたい方はご覧ください。