Claude Code Subagents: 実践ガイド（2026）

Claude Code と subagent を毎日使っている開発者、Jasmine より。

Claude Code の subagent とは？

subagent とは、メインエージェントが特定のタスクを処理するために起動できる Claude の専門化されたインスタンスであり、独自のコンテキストウィンドウ・独自のシステムプロンプト・独自のツールセットを持って動作し、その後に凝縮した結果をメインエージェントへ報告します。 一言でいえば、1 つの Claude に単一の会話の中で仕事全体を背負わせるのではなく、作業を小さなアシスタントたちに分割するということです。それぞれが単一の役割に特化した AI エージェントです。

メインエージェントをテックリードだと考えてみてください。大きな仕事が舞い込んだとき（たとえば「コードベース全体をセキュリティの観点でレビューして」）、テックリードはすべてのファイルを自分の頭の中で読むわけではありません。読み込み、要約し、報告してくれるセキュリティ専門家に任せます。subagent はまさにその専門家です。タスクの説明（システムプロンプト）を持ち、一定の権限（ツール）を与えられ、作業が終わると本当に必要な結論だけを返します。

同じセッションに指示を追加で打ち込むだけの場合との核心的な違いはこうです。Claude Code の subagent は分離されたコンテキストを持ちます。subagent が仕事をするために読み込まなければならない中間的な情報はすべてその「頭の中」にとどまり、メインセッションに漏れ出すことは決してありません。各 subagent は .claude/agents/ ディレクトリに置いたシンプルな Markdown ファイルで宣言し、Claude Code が自動的に認識します。

subagent はどのように動作するのか？（コンテキストの分離）

subagent の背後にある仕組みは コンテキストの分離（context isolation） と呼ばれます。これこそが subagent を使う本当の価値であり、単に「見せかけでもう 1 つの AI を立ち上げる」ことではありません。

典型的な実行は次のようになります。

1. メインエージェントがあなたのリクエストを受け取り、どのタスクを subagent に渡すべきかを決めます。
2. 具体的なタスクの説明とともに、対応する subagent を起動します。
3. subagent は 独自のコンテキストウィンドウ、つまり「思考のサンドボックス」の中で動作します。ファイルを読み、コマンドを実行し、問題を推論する。そのすべてを自分の空間の中で行います。
4. 終わると、subagent は全過程をメインセッションに吐き出すのではなく、凝縮した結果（要約、バグの一覧、コードスニペット）だけを返します。

You
 └─► Main agent (main context, lean)
 ├─► subagent: test-runner ──► returns: 2 tests failing
 ├─► subagent: security-scan ──► returns: 1 SQLi vulnerability
 └─► subagent: style-checker ──► returns: 5 lint warnings
 (each subagent = its own context window)

subagent は重いコンテキスト（何十ものファイルの読み込み、長大なログ）を「飲み込み」、その本質だけを「吐き出す」ため、メインセッションはクリーンなコンテキストを保ち、より長く持続します。これは一部にはトークンの節約（メインコンテキストが膨れ上がらない）であり、一部には 品質 の問題でもあります。メインエージェントが中間的なノイズで汚染されないため、その推論はより鋭いままに保たれます。この仕組みと範囲については、Anthropic の 公式 Claude Code Subagents ドキュメント（2026 年 8 月アクセス）で説明されています。

これを手作業で新しいチャットタブを開くのと区別すると分かりやすいです。複数のセッションを手動で行き来してチャットするときは、あなた自身が結果をあちこちにコピーして回ることになります。遅く、抜け落ちやすい。subagent なら、メインエージェントがフロー全体をオーケストレーションします。何を、誰に渡すかを決め、その結果を 1 回の作業ターンの中で自動的に縫い合わせます。ターミナルから離れる必要は一切ありません。

よく誤解される点が 1 つあります。コンテキストの分離は subagent を「頭の悪い」ものにするわけではありません。あなたが選んだのと同じモデルラインのままで、ただ必要なツールだけを持って、ちょうど 1 つのタスクに集中しているだけです。スコープを絞ることは、たいてい出力を悪くするどころか良くします。1 人に一度に 10 のことを求めるのではなく、専門家に 1 つの明確な仕事を与えるようなものです。

最初の subagent を作る - .claude/agents ファイル

ここが実践の中心部分です。subagent を作る方法は 2 つあります。/agents インターフェースを使う（初めての場合はおすすめ）か、Markdown ファイルを手で書くか。どちらも同じもの、つまり .claude/agents/ の中のファイルを生成します。

ステップ 1 - エージェントマネージャーを開く

Claude Code のセッション内で、次のように入力します。

/agents

インターフェースは既存のエージェントを一覧表示し、新しいエージェントの作成、スコープの選択、モデルの選択、メニューからのツール制限ができます。直接コントロールしたい場合は、このステップを飛ばして自分でファイルを書いても構いません。結果は同じです。

ステップ 2 - スコープを選ぶ：プロジェクトかユーザーか

エージェントファイルを置く場所は 2 つあり、正しい方を選ぶことが重要です。

• プロジェクトレベル - プロジェクトフォルダ内の .claude/agents/。このプロジェクトにのみ適用され、Git にコミットすればチーム全体で共有できます。プロジェクト固有のエージェント（たとえば、チームの規約を理解しているレビュアー）にはこちらを選びます。
• ユーザーレベル - ホームディレクトリの ~/.claude/agents/。あなたのすべてのプロジェクトに適用されます。どこでも手元に置いておきたいエージェント（たとえば汎用のドキュメントライター）にはこちらを選びます。

名前が衝突した場合は、プロジェクトレベルのエージェントがユーザーレベルより優先されます。

ステップ 3 - エージェントファイルを書く（実例）

下記の内容で .claude/agents/code-reviewer.md ファイルを作成します。上部が YAML フロントマター、本文が subagent のシステムプロンプトです。

---
name: code-reviewer
description: Review code for bugs, security, and maintainability. Use right after you write or change code.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior-level code reviewer. Your job:
- Read the code that just changed (use Read/Grep/Glob, do NOT edit files).
- Find logic bugs, security holes, and hard-to-maintain spots.
- Rank findings by severity: critical / should-fix / suggestion.
- Return a short list with file paths and line numbers.
Do not run write commands, do not commit, do not change code.

ステップ 4 - 確認する

もう一度 /agents を実行し、code-reviewer が一覧に表示されることを確認します。これで完了です。あなたは最初の subagent を作り上げました。これ以降、コードを変更した直後にはいつでも、Claude が自動的にそれを呼び出せますし、直接呼び出すこともできます。「code-reviewer subagent を使って、いま変更した内容を見てもらって」というように。

フロントマターのフィールド（name、description、tools、model）

フロントマターが subagent の振る舞いを決めます。覚えるべきフィールドはたった 4 つです。

価値ある 2 つのコツ：(1) 動詞と状況を使って明確な description を書きましょう（「〜の直後に使う」など）。これこそ Claude が適切なタイミングで適切なエージェントを自動呼び出しするために使うものだからです。(2) 読み取り専用のエージェントには、tools を Read, Grep, Glob に制限しましょう。そうすれば subagent は物理的に、うっかりファイルを編集したり削除したりできなくなります。

subagent の呼び出しと管理

subagent を起動する方法は 3 つあります。

1. 自動委任 - Claude が description フィールドに基づいて適切な subagent を選びます。あなたはいつも通り作業するだけで、コンテキストが一致したとき（たとえばコードの編集を終えた直後）に、Claude が自分で code-reviewer に引き渡します。
2. 直接呼び出し - リクエストの中でエージェントを名指しします。「code-reviewer subagent を使って決済モジュールをチェックして」というように。必要なものが正確に分かっているときは、これが最も確実な方法です。
3. /agents で管理する - インターフェースを開いてエージェントの一覧表示・編集・削除ができます。ファイルを手で開かずにモデルを切り替えたり、ツールを追加・削除したりできます。

呼ばれるはずだと思っているのに subagent が「まったく呼ばれない」場合、犯人はほぼ必ず曖昧すぎる description です。具体的に書き直せば解決します。

並列実行と複数 subagent のオーケストレーション

ここが subagent が本当に輝くところであり、ほとんどのガイドが飛ばす部分です。各 subagent が独自のコンテキストで動作するため、メインエージェントは同じコードベースに対して 複数の subagent を一度にファンアウト（並列展開） できます。

例：3 つの subagent を並列実行

機能を作り終えたばかりで、PR を出す前に全体チェックをしたいとします。順番に 1 つずつやる代わりに、こう頼みます。

Run 3 subagents in parallel on the current branch:
- test-runner: run the full test suite, report which tests fail
- security-scanner: scan the code that just changed for vulnerabilities
- style-checker: check lint and conventions
Combine all three into a single report.

3 つのエージェントはそれぞれ独立して動作し、必要なものを各自で読み込みます。そのあとメインエージェントが 3 つの簡潔なレポートを統合します。時間もコンテキストも節約できます。

トークンの面では、「X パーセント節約」を期待する前に仕組みを正しく理解しましょう。節約されるのはトークンの総量ではありません。3 つのエージェントを動かせば、3 つ分のトークンはやはりかかります。節約されるのは メインセッションのトークン です。すべてのテストログ、セキュリティスキャンの記録、lint の警告は各 subagent のコンテキスト内にとどまり、返ってくるのは結論の数行だけです。それこそがメインセッションが早々に埋まってしまうのを防ぎ、より長い思考の流れを保てる理由です。それが本当のメリットであって、固定のパーセンテージではありません。

複数レイヤーのオーケストレーション

もう 1 段上へ：ある subagent の出力が次の subagent の入力になります。典型的な explore -> plan -> implement のフローはこうです。

1) subagent "explorer": survey the codebase, return a module map + spots to change.
2) Feed that result to subagent "planner": lay out a step-by-step plan.
3) Feed the plan to subagent "implementer": execute it step by step.

これは強力なオーケストレーションパターンですが、その根底にある 1 つの重要な制限を理解しておく必要があります。

知っておくべき制限

subagent は 互いに直接コンテキストを共有しませんし、ピアツーピアで「会話」もしません。結果をメインエージェントに返すだけで、次の subagent へ情報を転送するのはメインエージェントです。起動のたびに 1 回のトークンの往復が発生します。ですから複数レイヤーのオーケストレーションには本物の力がある一方、コストもあります。使いすぎないようにしましょう。subagent が Skills／Hooks／MCP とどう違うのかを正確に理解するには、Skills・Subagents・Hooks・MCP を比較するガイドを読んでください。

すぐに使える subagent テンプレートをいくつか

コピー＆ペーストで使える 4 つのテンプレート。軽く調整して使い始めましょう。

1. 読み取り専用レビュアー（完全に安全）

---
name: safe-reviewer
description: Read-only code review that never edits files. Use to inspect before a merge.
tools: Read, Grep, Glob
model: sonnet
---
You only read and comment. Never run write commands. Return findings ranked by severity.

2. Test-runner

---
name: test-runner
description: Run the test suite and summarize failures. Use after editing code.
tools: Bash, Read, Grep
model: haiku
---
Run the project's tests, read the output, list failing tests with a short cause each.

3. Doc-writer

---
name: doc-writer
description: Write/update documentation and docstrings for new code.
tools: Read, Grep, Glob, Edit
model: sonnet
---
Read the code, write clear docs that match the repo's style. Do not change code logic.

4. Explorer

---
name: explorer
description: Survey an unfamiliar codebase, return an architecture map and entry points.
tools: Read, Grep, Glob
model: sonnet
---
Map out the modules, data flow, and the important files. Read only, never edit.

4 つのテンプレートすべてに注目してください。書き込みが不要なエージェントには、書き込み権限を与えていません。これは守る価値のある安全な習慣です。

subagent は Skills、Hooks、MCP とどう違うのか？

これら 4 つのビルディングブロックはよく混同されます。手早く見分ける方法はこうです。

要するに、subagent は仕事を分割し、Skills は手順を教え、Hooks はイベントを自動化し、MCP は接続を拡張します。どれを使えばよいかまだ迷うなら、4 つのビルディングブロックの完全比較がより深く掘り下げています。

よくある間違いと本当の制限

このセクションをわざわざ書くブログはほとんどありませんが、これこそ subagent を正しく使うのに役立つものです。

• 過剰な委任。 ごく小さなタスク（変数を 1 つリネームする、1 行修正する）を subagent に分割するのは逆効果です。トークンの往復とレイテンシのほうが、自分でやるよりコストがかかります。subagent は「コンテキストが重く、結果が軽い」作業のためのものです。
• 曖昧な description は自動呼び出しされない。 description が一般的すぎると、Claude はいつ引き渡せばよいか分かりません。使うべき具体的な状況を書き出しましょう。
• tools の制限を忘れる。 本来は読むだけのはずのレビュアーに書き込み権限を与えると、間違ったファイルを編集してしまうことがあります。常に最小限の権限を与えましょう。
• エージェントを並べすぎてトークンを浪費する。 5〜6 個のエージェントを並列で動かすのは見栄えがしますが、それぞれが課金対象の独立したセッションです。目的を持ってファンアウトしましょう。
• 分割すべきでないとき： タスクが現在の会話の全コンテキストを必要とする場合（たとえば、それまでの細部すべてが重要になる長いフローをデバッグしているとき）です。subagent はメインのコンテキストを見られないため、分割すると必要としているまさにそのコンテキストを失います。

書く手間を省く - AgentKit の 45 個のビルド済みエージェント

良い subagent を書くには、プロンプトを調整して何度もテストする労力がかかります。ゼロから書く代わりに、専門化されたエージェントの既製ライブラリが欲しいなら、AgentKit の 45 個のビルド済みエージェントは任意の近道になります。これは Claude Code 向けのキットで（OpenAI の AgentKit ではありません - ただの名前の衝突です）、108 以上のスキルとともに 45 エージェント = 17 Engineer + 28 Marketing を同梱しています。決める前にエージェントのカタログを見てみたいなら、AgentKit の 45 個のビルド済みエージェントの概要を読んでください。Engineer Kit は 99 ドルです（サイトに定期課金の記載はありません）。とはいえ、自分のリポジトリの規約に合ったエージェントをいくつか書けることは、今も学ぶ価値のある基礎スキルです。キットはあなたがより速く進むのを助けてくれるだけです。

よくある質問（FAQ）

subagent は追加でお金がかかりますか？

はい、間接的には。各 subagent は独自のコンテキストを持つセッションなので、自分のトークンを消費します。複数を並列で動かすと、単一のセッションより多くのトークンを使います。その代わり、メインのコンテキストがより軽く保たれるため、コンテキストの重い作業では全体としてなお効率的になり得ます。

subagent はいくつまで並列で実行できますか？

一度に複数の subagent をファンアウトできますが、実際に必要な数に抑えるべきです（レビュー作業なら 3〜4 個がたいてい妥当です）。ファンアウトを増やすほど、トークンを多く消費し、追跡も難しくなります。

subagent はメインの会話を覚えていますか？

いいえ。各 subagent は分離されたコンテキストウィンドウで動作し、メインエージェントが意図的に渡したものを除いて、メインセッションの履歴を見ることはできません。それが強み（クリーンなコンテキスト）であると同時に、心にとめておくべき制限でもあります。

subagent は Skills とどう違いますか？

subagent は仕事を割り当てられて独立して動作する専門化されたサブ AI です。Skills は Claude が従うために読み込まれる、パッケージ化された指示・手順です。一方は「あなたの代わりに仕事をする」もので、もう一方は「やり方を教える」ものです。

エージェントはプロジェクトレベルとユーザーレベルのどちらに置くべきですか？

チームのためにコミットしたいプロジェクト固有のエージェントは、プロジェクトレベル（.claude/agents/）に置きます。すべてのプロジェクトで使いたいエージェントは、ユーザーレベル（~/.claude/agents/）に置きます。名前が衝突した場合はプロジェクトレベルが勝ちます。

Claude Code Pro は必要ですか？

subagent は Claude Code の機能です。すでに加入しているどのプランの中でも使えます。プランの詳細（月額 20 ドルの Pro、Max など）については、Claude Code とは何かを参照してください。

まとめと次のステップ

subagent は Claude Code を単独のアシスタントから小さなチームへと変えます。仕事を分割し、並列で実行し、コンテキストをクリーンに保つ。まずは読み取り専用の code-reviewer でシンプルに始め、その力と限界の両方をつかんだら、オーケストレーションへと広げていきましょう。subagent と skill を組み合わせるには、次に Claude Code Skills とは何かを読んでください。適切なツールを選ぶには 4 つのビルディングブロックの比較をどうぞ。そして、ゼロから書きたくないなら、ビルド済みエージェントのライブラリを備えた AgentKit バンドル — 今なら 149 ドル（198 ドルから）を試してみてください。