Claude Codeのサブエージェントって何ができるの？
室谷今回はClaude Codeのサブエージェント機能を深掘りしていきましょう。これ、.AI（ドットエーアイ）コミュニティでも「どう使えばいいの？」ってよく聞かれるんですよね。
テキトー教師ですよね。講座でClaude Codeを教えていると、サブエージェントのあたりで「急に難しくなった」って声がよく出るんですよ。
でも、使いこなすと作業効率が全然変わってくる。
でも、使いこなすと作業効率が全然変わってくる。
室谷一言で言うと、サブエージェントは「専門担当を持つAIアシスタント」ですね。メインのClaude Codeとは別のコンテキストウィンドウで動いて、特定タスクを独立して処理してくれる。
テキトー教師教える立場から整理すると、サブエージェントには3つの核心があります。「独立したコンテキスト」「専門化されたツールアクセス」「独自のシステムプロンプト」の3つ。
この3つがセットで動くから、本当に専門家を雇ったみたいな動きをするんですよ。
この3つがセットで動くから、本当に専門家を雇ったみたいな動きをするんですよ。
室谷MYUUUでもこれ活用してます。コードレビュー専門のサブエージェントを設定しておくと、実装が終わった瞬間に自動でレビューしてくれる。
しかも本当に読み取り専用のツールしか持たせてないから、コードを誤って変更するリスクがない。
しかも本当に読み取り専用のツールしか持たせてないから、コードを誤って変更するリスクがない。
テキトー教師その「ツール制限」が地味に重要なんですよ。サブエージェントは与えたツールしか使えないから、「読むだけのエージェント」「書くだけのエージェント」みたいに役割を明確に切れる。
コミュニティのメンバーさんに「AIに何でもやらせようとするのが一番の罠」って伝えてるんですが、サブエージェントはその問題を構造的に解決してくれる仕組みなんです。
コミュニティのメンバーさんに「AIに何でもやらせようとするのが一番の罠」って伝えてるんですが、サブエージェントはその問題を構造的に解決してくれる仕組みなんです。
室谷2026年現在、Claude Codeに組み込まれたビルトインサブエージェントが4種類あります。まずはそれを理解するのが最初のステップですね。
| サブエージェント名 | モデル | 主な用途 |
|---|---|---|
| Explore | Haiku（高速・低レイテンシ） | コードベースの探索・検索 |
| Plan | メイン会話から継承 | プランモード時のリサーチ |
| General-purpose | メイン会話から継承 | 複雑なマルチステップタスク |
| statusline-setup | Sonnet | /statuslineコマンド実行時 |
テキトー教師このExploreエージェント、かなり賢くできていて。Haiku（軽量・高速モデル）で動くから速いし、読み取り専用ツールしか持ってないから安全。
Claudeがコードを探索するときは、メインの会話を汚さずにExploreが別ウィンドウで調べてくれる。
Claudeがコードを探索するときは、メインの会話を汚さずにExploreが別ウィンドウで調べてくれる。
室谷コンテキストウィンドウの節約、という観点で言うと・・・これ、経営的にもすごく重要で。大規模なコードベースを探索しながら実装するとなると、メインのコンテキストがどんどん消費される。
サブエージェントを使うと、「探索の結果」だけがメインに戻ってくるから、コンテキストの使い方が劇的に効率化されるんですよ。
サブエージェントを使うと、「探索の結果」だけがメインに戻ってくるから、コンテキストの使い方が劇的に効率化されるんですよ。
テキトー教師受講生さんからよく「Claude Codeがすぐ重くなる」って聞くんですが、原因のほとんどがコンテキストの無駄遣いですね。大量のファイルを読み込ませたり、試行錯誤を繰り返したりしているうち、気づいたら制限に当たっている。
サブエージェントでタスクを分離すると、これがかなり改善します。
サブエージェントでタスクを分離すると、これがかなり改善します。
サブエージェントの作り方：/agentsコマンドから始める
室谷実際の作り方に入りましょう。一番簡単なのは/agentsコマンドですね。
テキトー教師これ、知らない人が多いんですよ。Claude Codeの中で
作成・編集・削除が全部そこでできます。
/agentsと入力するだけでインタラクティブなUIが開く。作成・編集・削除が全部そこでできます。
室谷UIが開いたら「Create new agent」を選んで、場所を「Personal」か「Project」で選ぶ。Personalは
Projectは
~/.claude/agents/に保存されて全プロジェクトで使える。Projectは
.claude/agents/に保存されてそのプロジェクト専用。テキトー教師MYUUUさんはどっちを主に使ってます？
室谷プロジェクト固有のものはProject、汎用的なものはPersonalですね。コードレビューエージェントはPersonalにして全プロジェクトで使い回してます。
特定のAPIとの連携エージェントはProjectに置いてチームでGit管理してる。
特定のAPIとの連携エージェントはProjectに置いてチームでGit管理してる。
テキトー教師そのGit管理の観点、講座でも強調するようにしてます。
これ、チーム開発での標準化に使えますよ。
.claude/agents/はプロジェクトのリポジトリに入れてバージョン管理できるから、チーム全員が同じサブエージェントを使える。これ、チーム開発での標準化に使えますよ。
室谷/agentsを使うと、Claudeが自動でサブエージェントを生成してくれる機能もあります。「こういうことをやるサブエージェントを作って」って説明するだけで、名前・説明文・システムプロンプトまで自動で書いてくれる。
テキトー教師これは便利ですよね。ゼロから書くとなると、どう書けばいいか迷う人が多い。
「コードのセキュリティ問題を専門的にチェックするエージェント」って説明するだけで、それに合ったプロンプトを生成してくれる。あとから自分でカスタマイズすればいい。
「コードのセキュリティ問題を専門的にチェックするエージェント」って説明するだけで、それに合ったプロンプトを生成してくれる。あとから自分でカスタマイズすればいい。
室谷実際の設定の仕組みを解説しましょう。サブエージェントはMarkdownファイルで定義されていて、YAMLのフロントマターで設定を書くんですよ。
テキトー教師手動で作る場合のファイル構造を見てみましょうか。
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- No exposed secrets or API keys
- Input validation implemented
- Proper error handling
このフォーマット、シンプルだけど奥が深いんですよね。
nameは一意な識別子。descriptionはClaudeがこのエージェントをいつ使うかの判断基準になる、ここが一番重要。toolsで使えるツールを絞る。modelでどのモデルで動かすかを指定。テキトー教師descriptionの書き方、ここが実は一番のポイントなんですよ。Claudeはこの説明文を読んで「このタスクはこのサブエージェントに任せよう」と自動的に判断する。だから「Use proactively after code changes」みたいに、使うタイミングを明示的に書くと効果的です。
室谷設定できる主なフィールドをまとめると・・・
| フィールド | 必須 | 説明 |
|---|---|---|
| name | 必須 | 小文字とハイフンのみ使える一意な識別子 |
| description | 必須 | Claudeがいつ委任するかの判断基準 |
| tools | 任意 | 使えるツールのリスト（省略時は全ツールを継承） |
| disallowedTools | 任意 | 使用禁止ツールのリスト |
| model | 任意 | sonnet / opus / haiku / フルモデルID / inherit |
| permissionMode | 任意 | 権限モードの設定 |
| maxTurns | 任意 | 最大ターン数 |
| skills | 任意 | 起動時に読み込むスキル |
| memory | 任意 | 永続メモリのスコープ（user/project/local） |
| hooks | 任意 | このサブエージェント専用のフック |
| color | 任意 | UIでの表示色 |
| background | 任意 | true にすると常にバックグラウンドで実行 |
| isolation | 任意 | worktree で独立したGitワークツリーで実行 |
テキトー教師このフィールド一覧、これだけで記事1本書けそうですよね（笑）。でも実際の使い始めは
あとは必要になったら追加で学べばいい。
name description tools model の4つだけ覚えておけば十分。あとは必要になったら追加で学べばいい。
室谷そうですね。「完璧に理解してから使う」より「まず使ってみて、困ったら深掘りする」の方が断然早い。
モデルとツールの選び方：HaikuとSonnetをどう使い分けるか
テキトー教師modelフィールドの選び方、これもよく聞かれる質問ですね。室谷基本的な考え方は「スピードが必要でシンプルなタスクはHaiku、複雑な推論が必要ならSonnet、最高難度のタスクならOpus」ですね。コスト差が結構あるので、ここは意識したいところ。
テキトー教師具体的に言うと、ファイル探索とか単純なコード検索ならHaikuで全然いいですよ。Claudeが組み込みのExploreサブエージェントにHaikuを使ってるのもそれが理由。
でも「セキュリティ脆弱性を検出する」「複雑なアーキテクチャを分析する」みたいなタスクはSonnetを選ぶべきですね。
でも「セキュリティ脆弱性を検出する」「複雑なアーキテクチャを分析する」みたいなタスクはSonnetを選ぶべきですね。
室谷model: inheritという設定もあって、これにするとメイン会話と同じモデルを使う。指定しなかった場合のデフォルトもinheritです。だからProプランで使ってるならSonnet、Maxプランなら親のモデルを引き継ぐ。
テキトー教師ここで面白い使い方があって。メイン会話ではOpusを使いつつ、探索系のサブエージェントはHaikuに指定する、みたいなことができる。
重要な判断だけ高性能モデルに任せて、ルーティン作業は軽量モデルに任せる、っていうコスト最適化ができるんですよ。
重要な判断だけ高性能モデルに任せて、ルーティン作業は軽量モデルに任せる、っていうコスト最適化ができるんですよ。
室谷MYUUUのエンジニアに「上手いアーキテクチャ」って説明するとき、まさにこれを例に出しますね。「AIを一様に高性能モデルに任せるのは非効率。
役割に応じてモデルを使い分けるのが本質」と。
役割に応じてモデルを使い分けるのが本質」と。
テキトー教師モデル解決の優先順位も整理しておきましょう。
| 優先順位 | 設定方法 |
|---|---|
| 1（最優先） | CLAUDE_CODE_SUBAGENT_MODEL環境変数 |
| 2 | 呼び出し時に渡したmodelパラメータ |
| 3 | サブエージェント定義のmodelフィールド |
| 4（最低） | メイン会話のモデル |
室谷CLAUDE_CODE_SUBAGENT_MODEL環境変数、これCIで使うと便利なんですよ。本番デプロイのパイプラインでコストを制御したいときに、環境変数一つで全サブエージェントを軽量モデルに切り替えられる。テキトー教師ツール制限の話も続けましょう。サブエージェントにツールを与えすぎると「なんでもできるAI」になっちゃって、かえって危険なんですよね。
「このエージェントは読むだけ」「こっちは書くだけ」みたいに明確に分けるのが安全設計の基本。
「このエージェントは読むだけ」「こっちは書くだけ」みたいに明確に分けるのが安全設計の基本。
室谷toolsフィールド（許可リスト）とdisallowedToolsフィールド（禁止リスト）の2種類があって、使い方が違います。toolsで「Read, Grep, Glob, Bash」と書くと、この4つしか使えない。MCPツールも全部使えなくなる。
テキトー教師対して
disallowedToolsは「これ以外全部使える」という設定ですね。disallowedTools: Write, Editと書くと、ファイルの書き込みと編集だけが禁止されて、それ以外のツール（MCP含む）は全部使える。室谷両方設定した場合は
disallowedToolsが先に適用されて、残ったプールからtoolsで絞り込む、という順序なので注意が必要ですね。テキトー教師MCP サーバーのスコープ管理もできるのが地味に便利ですよね。
メイン会話にはPlaywrightのMCPを持たせず、ブラウザテスト専用エージェントだけに持たせる、みたいな設計が可能です。
mcpServersフィールドで、特定のMCPサーバーをそのサブエージェントだけに与えられる。メイン会話にはPlaywrightのMCPを持たせず、ブラウザテスト専用エージェントだけに持たせる、みたいな設計が可能です。
室谷これ、コンテキストの節約にもなるんですよ。MCPサーバーのツール定義がメイン会話に入ってこないから、コンテキストが太らない。
サブエージェントが起動したときだけMCPに接続して、終わったら切断する。スマートな設計です。
サブエージェントが起動したときだけMCPに接続して、終わったら切断する。スマートな設計です。
---
name: browser-tester
description: Webアプリのブラウザテストを実行する専用エージェント
mcpServers:
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
---
ブラウザを使ってWebアプリケーションのUIテストを実行します。
指定されたURLにアクセスし、インタラクションをテストして結果をレポートします。
このmcpServersの書き方、インライン定義とサーバー名参照の2種類あります。上の例はインライン定義で、そのサブエージェントにだけPlaywrightを使わせる。
すでにセッションで設定済みのMCPサーバーを名前で参照することもできます。
すでにセッションで設定済みのMCPサーバーを名前で参照することもできます。
サブエージェントを明示的に呼び出す方法
室谷次はサブエージェントの呼び出し方ですね。自動的に委任される場合と、明示的に呼び出す場合があります。
テキトー教師自動委任は、Claudeがタスクの内容とサブエージェントのdescriptionを照合して「このタスクはこのエージェントに任せよう」と判断するケースですよね。コード変更後に「Use proactively after code changes」と書かれたレビューエージェントが自動的に起動する、みたいな。
室谷明示的に呼び出す方法が3パターンあって、これをきちんと使い分けるのが重要ですね。
- 自然言語で指定: 「code-reviewerエージェントを使って直近の変更をチェックして」と書く。Claudeが判断して委任。
- @メンション:
@"code-reviewer (agent)"と書くと、そのエージェントを確実に使う。 - セッション全体で固定:
claude --agent code-reviewerで起動すると、そのセッション全体がそのエージェントのシステムプロンプトで動く。
テキトー教師@メンション、これはタイプアヘッドで候補が出るので使いやすいですよ。
「確実にこのエージェントを使いたい」ときは@メンションが一番確実ですね。
@を入力するとファイルもエージェントも一覧で選べる。「確実にこのエージェントを使いたい」ときは@メンションが一番確実ですね。
室谷claude --agentでセッション全体をそのエージェントにする使い方、これ面白いんですよ。たとえば「このプロジェクトではコードレビューモードで常に動かしたい」なら.claude/settings.jsonに書ける。{
"agent": "code-reviewer"
}
そうすると、プロジェクトを開いたら常にそのエージェントのシステムプロンプトで動くわけですね。CLAUDE.mdの代わりにサブエージェント定義でプロジェクト固有のAI設定を管理する、っていう発想の転換ができる。
室谷foreground（フォアグラウンド）とbackground（バックグラウンド）の違いも押さえておきましょう。フォアグラウンドは完了まで待つ、バックグラウンドは並行して走る。
デフォルトはClaude自身が判断しますが、「バックグラウンドで実行して」って指示することもできる。
デフォルトはClaude自身が判断しますが、「バックグラウンドで実行して」って指示することもできる。
テキトー教師フロントマターで
途中で「これいいですか？」って聞いてこないから、邪魔されずに作業を続けられる。
background: trueを設定すると、常にバックグラウンドで動くサブエージェントになりますよ。バックグラウンドエージェントは起動前に必要な権限を全部確認して、あとは自律的に動く。途中で「これいいですか？」って聞いてこないから、邪魔されずに作業を続けられる。
室谷Ctrl+Bでも実行中のタスクをバックグラウンドに切り替えられるんですよ。「あ、これ待ってなくていいな」ってなったら即バックグラウンド化できる。
サブエージェントの並列実行：コンテキストを節約しながら効率化する
テキトー教師並列実行の話、これが一番インパクトが大きい使い方ですよね。
室谷そうですね。独立した調査・分析を複数のサブエージェントに同時に走らせると、時間が全然変わります。
たとえば「authentication、database、APIモジュールをそれぞれ別のサブエージェントで並列調査して」という指示一つで、3つのエージェントが同時に動く。
たとえば「authentication、database、APIモジュールをそれぞれ別のサブエージェントで並列調査して」という指示一つで、3つのエージェントが同時に動く。
テキトー教師この「並列リサーチ」パターン、Xでもよく出てきますよね。コミュニティのメンバーさんが「Claude Codeのサブエージェントで並列実行してみたら3倍速くなった」みたいな投稿をよく見ます。
室谷テスト実行もそうですね。「テストを全部実行して失敗したテストとエラーメッセージだけレポートして」をサブエージェントに任せると、大量のテスト出力がメインのコンテキストに流れ込んでこない。
サマリーだけが返ってくる。
サマリーだけが返ってくる。
テキトー教師このパターン、「高ボリューム操作の分離」って呼ばれてますね。ログファイルの処理、ドキュメントの取得、テストの実行、どれも出力が大量になるんだけど、サブエージェントに任せると結果のサマリーだけがメインに戻ってくる。
室谷コードのデバッグで「競合仮説を並列検証する」という使い方もあります。バグの原因が2つ考えられるとき、それぞれの仮説を別のサブエージェントに検証させて、どちらが正しいか競わせる。
これ、人間のチームでもやる手法なんですよね。
これ、人間のチームでもやる手法なんですよね。
テキトー教師「競合仮説デバッグ」は教育的にも面白い使い方ですよ。受講生さんに「AIを一つのセッションで全部考えさせないで、仮説ごとに分けてみて」と言うと、デバッグの質が上がることが多い。
室谷並列実行する際に注意したいのが、各サブエージェントの結果がメインに返ってきたとき、またコンテキストを消費するという点ですね。各エージェントの結果を詳細に返させると、結局コンテキストが太る。
だから「サマリーだけ返せ」という指示をしっかり入れるのが重要。
だから「サマリーだけ返せ」という指示をしっかり入れるのが重要。
テキトー教師あと、サブエージェントは別のサブエージェントを呼び出せない（ネストができない）という制限があります。これ、引っかかる人が多い。
サブエージェント内でまたAgentツールを呼ぼうとしてもできないんですよ。
サブエージェント内でまたAgentツールを呼ぼうとしてもできないんですよ。
室谷その場合はエージェントチーム（Agent Teams）か、メイン会話からサブエージェントをチェーンする方法を使う必要があります。「code-reviewerサブエージェントで問題を見つけて、次にoptimizerサブエージェントで修正して」みたいな連鎖的な指示ができる。
テキトー教師チェーンパターン、これは順番が大事なタスクに向いてますよね。前のエージェントの結果を次のエージェントに渡す。
探索→分析→実装→検証、みたいなフローを組める。
探索→分析→実装→検証、みたいなフローを組める。
サブエージェントのスコープ管理：どこに置くかで変わること
室谷スコープ管理の話をしましょう。サブエージェントはどこに置くかで優先順位が変わるんです。
| 場所 | スコープ | 優先順位 |
|---|---|---|
| Managed settings | 組織全体 | 1（最高） |
| --agents CLIフラグ | 現在のセッション | 2 |
| .claude/agents/ | 現在のプロジェクト | 3 |
| ~/.claude/agents/ | 自分の全プロジェクト | 4 |
| プラグインのagents/ | プラグインが有効な場所 | 5（最低） |
テキトー教師同じ名前のエージェントが複数の場所にある場合、優先順位が高い方が勝ちますよね。たとえば組織で配布したcode-reviewerと、個人で作ったcode-reviewerがあったら、組織の方が使われる。
室谷これ、チーム管理の観点では重要で。組織レベルで標準のレビューエージェントを配布して、個々のエンジニアが勝手にオーバーライドできないようにする、みたいな運用ができます。
テキトー教師逆に言うと、プロジェクトの
.claude/agents/に置いたエージェントが個人の~/.claude/agents/の同名エージェントより優先されるから、プロジェクト固有のカスタマイズが個人設定に勝てる。室谷CLIで渡す方法もあって、これが便利なんですよ。
ファイルを作らずにセッション限定のエージェントを作れる。
claude --agentsフラグでJSON形式でエージェントを定義できる。ファイルを作らずにセッション限定のエージェントを作れる。
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'
CI/CDパイプラインでの活用に向いてますよね。テスト用に一時的なエージェントをその場で定義して、セッションが終わったら消える。
スクリプトでエージェントを動的に生成する、みたいな使い方もできる。
スクリプトでエージェントを動的に生成する、みたいな使い方もできる。
室谷ちなみに、エージェントの定義はセッション開始時に読み込まれます。ファイルを手動で追加した場合はセッションを再起動するか、
/agentsコマンドで即時読み込みする必要があります。永続メモリとhooks：サブエージェントを賢くする仕組み
テキトー教師永続メモリの機能、これを知ってる人が少ないんですよ。
室谷memoryフィールドを設定すると、サブエージェントが会話をまたいで学んだことを保持できる。「このコードベースではこういうパターンが多い」「過去にこのバグが出た」みたいな知識を蓄積していく。テキトー教師スコープは3種類あります。
userは全プロジェクト共通（~/.claude/agent-memory/エージェント名/）、projectはプロジェクト固有でGit管理可能（.claude/agent-memory/エージェント名/）、localはプロジェクト固有だけどGitに入れたくない場合。室谷コードレビューエージェントに
memory: projectを設定して「このリポジトリで繰り返し出る問題を記録して」と指示しておくと、時間が経つにつれて「このチームはここが弱い」という知識を持ったエージェントになっていく。テキトー教師人間のエンジニアが長年同じプロジェクトで「このコードは過去にこういう問題が出た」という知識を持つのと同じ発想ですよね。AIに制度的記憶を持たせる、という考え方。
室谷hooks機能も重要です。サブエージェント用にフロントマターでhooksを定義すると、そのエージェントが動いている間だけそのhookが有効になる。
テキトー教師たとえばBashコマンドの実行前に検証スクリプトを走らせる、みたいな使い方ができますよね。読み取り専用のDBクエリしか許可しないエージェントを作りたいとき、hookでSQL文をチェックしてINSERT/UPDATEをブロックする。
---
name: db-reader
description: 読み取り専用のデータベースクエリを実行する
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
フック、これを使いこなすとセキュリティのガードレールをきちんと設計できる。ツール制限だけでは防げないケースも、hookで補完できる。
テキトー教師isolation: worktreeという設定もあって、サブエージェントを独立したGitワークツリーで動かせます。本番のファイルを汚さずに、コピーした環境で思い切り実験できる。変更がなければワークツリーは自動で削除されるから、後片付けも自動。
室谷実験的な変更を試す「探索系エージェント」に使いたい設定ですね。「このアーキテクチャ変更がどうなるか試してみて」をisolationありのエージェントに任せると、本番コードへの影響ゼロで実験できる。
サブエージェントとエージェントチームの違い
テキトー教師ここ、一番混乱しやすいポイントですよね。サブエージェントとエージェントチーム（Agent Teams）の違い。
室谷シンプルに言うと「連絡が取れるかどうか」の違いです。サブエージェントは結果をメインに返すだけ。
エージェントチームはエージェント同士が直接メッセージをやり取りできる。
エージェントチームはエージェント同士が直接メッセージをやり取りできる。
テキトー教師整理するとこうなりますよね。
| 比較項目 | サブエージェント | エージェントチーム |
|---|---|---|
| コンテキスト | 独自のウィンドウ、結果を呼び出し元に返す | 独自のウィンドウ、完全に独立 |
| コミュニケーション | メインエージェントへの報告のみ | エージェント同士が直接やり取り |
| 調整 | メインエージェントが全体を管理 | 共有タスクリストで自己調整 |
| 最適用途 | 結果だけが重要な集中タスク | 討議・協力が必要な複雑な作業 |
| トークンコスト | 低め（結果のサマリーのみメインに返る） | 高め（各エージェントが独立したClaudeインスタンス） |
室谷エージェントチームはまだExperimentalで、
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1で有効化する必要があります。バージョンはv2.1.32以降が必要。テキトー教師この室谷さんのポストにある「判断基準はシンプル」、これが実践的ですよね。「担当を分けられるか？」「相互にやり取りが必要か？」の2問だけで判断できる。
室谷両方YesならAgent Teams、片方Noならサブエージェントか単体で十分、ということですね。エージェントチームはコストが3〜7倍になるので、本当に必要なときだけ使うべきです。
テキトー教師実際のプロダクション用途だと、フロントエンド・バックエンド・テスト担当をそれぞれ独立したエージェントに任せて、互いに「APIの仕様はこうしたよ」「じゃあそれに合わせてフロントを修正するね」みたいなやり取りができる。これはサブエージェントにはできない。
室谷一方でサブエージェントの方が圧倒的に使いやすくて低コストですよね。「コードを読んで問題を報告してほしい」「テストを実行してサマリーを返してほしい」レベルのタスクなら、サブエージェントで十分。
スキル（Skills）との違い：使い分けの判断基準
テキトー教師サブエージェントと混同しやすいのが「スキル（Skills）」ですよね。
室谷スキルは再利用可能なプロンプトやワークフローをメイン会話のコンテキストで実行するもの。サブエージェントは独立したコンテキストで動く。
この違いが大きい。
この違いが大きい。
テキトー教師教える立場から言うと、「サブエージェント＝外部委託、スキル＝社内ルール集」みたいなイメージで説明してます。スキルは「このチームではこうやる」という手順書をAIに読み込ませる。
サブエージェントは「この仕事はAのチームに任せる」みたいな役割分担。
サブエージェントは「この仕事はAのチームに任せる」みたいな役割分担。
室谷サブエージェントにスキルを持たせることもできます。フロントマターの
skillsフィールドで、そのエージェントが起動時に読み込むスキルを指定できる。---
name: api-developer
description: APIエンドポイントを実装する
skills:
- api-conventions
- error-handling-patterns
---
これ、スキルの内容がエージェントのコンテキストに丸ごと注入されるんですよ。「このエージェントが動く間は、このスキルの知識を持っている」という状態を作れる。
親会話からスキルを継承しない点も重要で、明示的にリストしないと使えない。
親会話からスキルを継承しない点も重要で、明示的にリストしないと使えない。
室谷使い分けの基準をまとめると・・・
- メイン会話でやりたいこと → スキル
- 独立したコンテキストでやりたいこと → サブエージェント
- 複数エージェントが相互通信しながらやりたいこと → エージェントチーム
- サブエージェントをネストしたい → できないので、メイン会話からチェーンする
テキトー教師あとは
「会話の中で既にわかってることについてちょっと聞きたい」だけなら
/btwコマンドという選択肢もありますよね。フルのコンテキストが見えるけどツールアクセスなし、結果は会話履歴に残らない、という簡易な質問ツール。「会話の中で既にわかってることについてちょっと聞きたい」だけなら
/btwで十分。サブエージェントの実践的な使い方：よくあるパターン5選
室谷実際の使い方、具体例で見ていきましょう。よく聞かれるパターンをまとめました。
テキトー教師パターン1は「コードレビュー自動化」ですよね。
室谷はい。コミットのたびに自動でレビューするエージェントを設定する。
description に「Use immediately after writing or modifying code」と書いて、Explore, Grep, Globだけを持たせる。これだけでコード変更のたびに自動的にレビューが走る。
description に「Use immediately after writing or modifying code」と書いて、Explore, Grep, Globだけを持たせる。これだけでコード変更のたびに自動的にレビューが走る。
テキトー教師パターン2は「テスト実行と失敗サマリー」ですね。テストを全部実行するとログが数千行になることもある。
それをサブエージェントに押し込んで「失敗したテストとエラーだけ返して」と言うと、メインのコンテキストはクリーンなまま。
それをサブエージェントに押し込んで「失敗したテストとエラーだけ返して」と言うと、メインのコンテキストはクリーンなまま。
室谷パターン3は「並列ドキュメント調査」。複数のドキュメントやAPIリファレンスを同時に調べたいとき、調べるごとにメインに流れ込んでくるとコンテキストが溢れる。
各ドキュメントを別々のサブエージェントに調べさせて、要点だけ返させる。
各ドキュメントを別々のサブエージェントに調べさせて、要点だけ返させる。
テキトー教師パターン4は「データベースクエリの安全実行」。先ほどのdb-readerみたいに、read-onlyクエリしか実行できないエージェントを作って、それ経由でのみDBアクセスを許可する。
hookでSQL文をバリデーションするガードレールを入れると完璧。
hookでSQL文をバリデーションするガードレールを入れると完璧。
室谷パターン5は「ブラウザテストの自動化」。PlaywrightのMCPをメイン会話に持たせると常にMCPのツール定義がコンテキストを占有する。
ブラウザテスト専用エージェントにだけPlaywrightを持たせることで、普段はコンテキストがクリーン。
ブラウザテスト専用エージェントにだけPlaywrightを持たせることで、普段はコンテキストがクリーン。
テキトー教師この5パターン、全部「コンテキストの節約」という共通原理から来てるんですよね。サブエージェントの本質は「必要な情報だけメインに返す」設計。
これを意識するだけで使い方が大きく変わる。
これを意識するだけで使い方が大きく変わる。
室谷最近のバージョンではサブエージェントの「再開（Resume）」もできるようになりました。一度終わったサブエージェントの会話履歴を保持して、「さっきのレビューの続きをして」という指示で前の会話から再開できる。
テキトー教師~/.claude/projects/{project}/{sessionId}/subagents/にサブエージェントのトランスクリプトが保存されてるんですよね。30日間は保持されるから、だいぶ後から「あのエージェントのやり取りを続けたい」というのも可能。室谷このv2.1.88の更新で「never delegate understanding（理解していないタスクをサブエージェントに丸投げするな）」という原則が追加されたのは、本当に重要なポイントで・・・。委任する前に必ずメインが理解を検証する必要がある。
「よしなにやっといて」は最悪の指示、という話と全く同じ。
「よしなにやっといて」は最悪の指示、という話と全く同じ。
テキトー教師「理解してから委任する」。人間のマネジメントでも同じですよね。
何をやってほしいか自分で理解してから部下に任せないと、ピントがずれた結果が返ってくる。
何をやってほしいか自分で理解してから部下に任せないと、ピントがずれた結果が返ってくる。
よくある質問（FAQ）
室谷よく聞かれる質問をまとめておきましょう。
テキトー教師Q. サブエージェントはいくつまで作れますか？
室谷公式ドキュメントに明確な上限は書かれていません。ただ、作りすぎると管理が大変になるので、本当に必要なものだけに絞るのが実践的です。
テキトー教師Q. サブエージェントのコストはどうなりますか？
室谷サブエージェントが使ったトークンも普通にカウントされます。特に並列実行すると複数のエージェントが同時にトークンを消費するので、コストは増えますね。
エージェントチームよりは低コストですが、使いすぎに注意は必要。
エージェントチームよりは低コストですが、使いすぎに注意は必要。
テキトー教師Q. サブエージェントにMYUUU独自のデータやナレッジを持たせられますか？
室谷できます。
skillsフィールドでスキルを読み込ませる、memoryフィールドで永続メモリを使う、システムプロンプトに直接書く、の3通りの方法があります。テキトー教師Q. claude code subagentのskillsって何が使えますか？
室谷公式ドキュメントのSkillsページに詳細が載っています（）。カスタムスキルを作って持たせることもできますし、
.claude/skills/に置いたスキルを名前で参照できます。テキトー教師Q. サブエージェントがエラーになったときはどうすればいいですか？
室谷まずバックグラウンドで実行中のサブエージェントがパーミッション不足で止まっている場合、新しいフォアグラウンドのサブエージェントで同じタスクをやり直すのが推奨です。事前に権限の確認ができるので。
まとめ：Claude Codeのサブエージェントをどう活用するか
室谷まとめに入りましょう。サブエージェントの核心は「コンテキストの分離」と「役割の専門化」の2つに尽きます。
テキトー教師使い始めはシンプルで十分です。まず
名前・説明文・ツール制限・モデルの4つを設定するだけで動く。
/agentsコマンドで最初のエージェントを作ってみる。名前・説明文・ツール制限・モデルの4つを設定するだけで動く。
室谷やってみて効果を実感してから、永続メモリやhooks、スキル連携などを追加していく。最初から全部完璧にしようとしないことですね。
テキトー教師講座で教えていると「コードレビューエージェントを一つ作るだけで、その日から体験が変わる」という感想をよくもらいます。まず動かしてみると、その違いがすぐにわかる。
室谷サブエージェント、エージェントチーム、スキルの使い分けは、最初は難しく感じるかもしれませんが・・・「一人でできるか、連絡が必要か、社内ルールか」で考えると整理しやすいですね。
テキトー教師前回の記事でClaude Codeの基本を学んだ方は、次のステップとしてぜひサブエージェントを試してみてください。きっと「これ、もっと早く知りたかった」となるはずです。