メインコンテンツへスキップ
見出し画像

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 や Codex の新しい手順の記事が届きます。ぜひフォローしてください。

    この先で分かること(今後の有料記事)

    • そのままコピーして使えるサブエージェントの実物(調査・校閲・レビュー・実装の役割分担)

    • 複数のサブエージェントを並べて、仕事を分担させる設計

    • 実際に起きた失敗と、直し方の記録

    まさのAI実務ラボ|Codex・Claude Code では、有料記事が読み放題になります。テンプレートや指示文をまとめて使いたい方はご覧ください。

    あなたへのおすすめ