【Claude Code】サブエージェントの活用法と注意点を詳しく解説

Claude Code のサブエージェントって、何ができるの？
サブエージェントを使って Claude Code の作業をもっと効率化したい！

Claude Code を毎日使っていると、

「探索タスクでコンテキストが膨れ上がる」
「大きな作業を順番にしか進められない」

という壁にぶつかります。

そこで活躍するのが Claude Code のサブエージェント です。独立したコンテキストで動く専門ワーカーを複数立ち上げられる仕組みで、使いこなせると Claude Code が別物になります。

Claude Codeのサブエージェントとは何か

サブエージェントというと難しそうに聞こえますが、仕組みはシンプルです。

「Claude Code が抱えきれない作業を、独立した子プロセスに外注する」——それだけです。

ここでは、以下の内容について詳しく解説します。

Claude が自動で呼び出すサブエージェントの仕組み

Claude Code は複雑なタスクを処理するとき、自動的にサブエージェント（子プロセス）をspawnします。

サブエージェントは親の会話とは完全に独立した、まっさらなコンテキストウィンドウで動作します。作業が終わると結果のサマリーだけを親に返し、子プロセス自身は閉じられます。

これを実現しているのが Agent tool（v2.1.63以前は「Task tool」という名称でした）です。Claude Code 自身がこのツールを内部的に使って、コードベースの探索・大規模ファイルの解析・繰り返し処理などをサブエージェントに委ねています。つまり、特に意識していなくても Claude Code はすでにサブエージェントを活用しています。

カスタムサブエージェントはその仕組みを「自分でも定義できるようにした」機能です。後述する .claude/agents/ に設定ファイルを置くだけで、自分専用の専門ワーカーを作れます。

コンテキスト分離が生む3つのメリット

サブエージェントの核心はコンテキスト分離です。メイン会話とは別のコンテキストウィンドウで動くことで、次の3つのメリットが生まれます。

• コンテキスト汚染を防げる：調査で大量のファイルを読んでも、メイン会話のコンテキストが膨らまない
• 並列処理ができる：複数の独立したタスクをサブエージェントに同時に委ねられる
• 精度が上がる：役割を絞った専門エージェントは判断ブレが少ない

私が一番実感したのは「コンテキスト汚染を防げる」点です。以前は大きなリポジトリを調査するたびにコンテキストウィンドウが詰まって、同じセッションで続きの作業ができなくなっていました。サブエージェントに調査を任せてから、それがなくなりました。

Claude Codeのサブエージェント設定手順

カスタムサブエージェントは、.claude/agents/ に Markdown ファイルを1つ置くだけで作れます。ここからは実際に作って動かすまでの流れを4ステップで解説します。

ここでは、サブエージェントの設定手順について解説します。

【ステップ1】.claude/agents/にMarkdownファイルを作る

配置場所は用途によって2つあります。選び方は次のとおりです。

ファイル名がエージェントの識別子になります。code-reviewer.md なら「コードレビューエージェント」として登録されます。チーム共有のルールは .claude/agents/ に置いてGitコミットすると、全員が同じエージェントを使えます。

まず .claude/agents/ ディレクトリがなければ作ります：

mkdir -p .claude/agents

【ステップ2】frontmatterにname・description・model・toolsを書く

Markdown ファイルの冒頭に --- で囲んだYAMLのfrontmatterを書きます。コードレビュー専門エージェントを例にとると、こうなります：

---
name: コードレビュー専門エージェント
description: コードの品質レビュー・バグ検出・改善提案を行うエージェント。Readでコードを読んでレビューしてほしいときに呼び出す。
model: claude-sonnet-4-6
tools:
  - Read
  - Bash
---

4つのフィールドの役割はそれぞれこうです：

• name：エージェントの表示名（呼び出すときに使う）
• description：どんなタスクに最適かを書く。ここの内容で Claude Code が自動ルーティングを判断するため、具体的に書くほど精度が上がる
• model：使用するモデルID。単純タスクは claude-haiku-4-5、複雑な判断は claude-sonnet-4-6 を指定してコストを最適化できる
• tools：使えるツールを制限する。書き込みが不要な調査エージェントは Read だけに絞ると安全

【ステップ3】本文にシステムプロンプトを書く

frontmatterの --- の直後から、自然文でシステムプロンプトを書きます。「何を見て（入力）・何をして（処理）・どんな形式で返すか（出力）」の3点を書くと精度が安定します。先ほどのコードレビューエージェントの完成形はこうなります：

---
name: コードレビュー専門エージェント
description: コードの品質レビュー・バグ検出・改善提案を行うエージェント。Readでコードを読んでレビューしてほしいときに呼び出す。
model: claude-sonnet-4-6
tools:
  - Read
  - Bash
---

あなたはコードレビューの専門家です。

## 役割
- 指定されたファイルのコードを読み、品質・バグ・セキュリティの3点からレビューする
- 問題点は「深刻度（高/中/低）」と「修正案」をセットで報告する

## 出力形式
1. 総評（3文以内）
2. 指摘事項（深刻度・場所・内容・修正案）
3. 改善提案（任意）

## 制約
- ファイルの読み取りのみ行う（書き込みは絶対に行わない）
- レビューしていないファイルについて推測で言及しない

制約セクションを入れておくとエージェントの暴走を防げます。「書き込みは行わない」「〇〇はしない」という明示的な禁止ルールが、意図しない操作を防ぐ最初のガードレールになります。

【ステップ4】呼び出して動作を確認する

ファイルを保存したら、Claude Code 上で /agents と入力してください。登録済みエージェントの一覧が表示され、先ほど作ったエージェント名があれば読み込み成功です。

呼び出し方は2種類あります：

• 自動委譲（おすすめ）：「〇〇のコードをレビューしてください」と依頼するだけ。Claude Code が description を読んで自動でルーティングしてくれる
• 手動指定：「コードレビュー専門エージェントを使って〇〇をレビューして」と名前を明示して呼び出す

エージェントが動き出すと、会話画面にサブエージェントのセッションが展開されます。Agent View（v2.1.139以降）ではサブエージェントのセッションを一覧で確認でき、どのエージェントが動いているかを把握できます。

Claude Codeのサブエージェント並列活用法

サブエージェントの最大の強みは並列処理です。これを使いこなすと、時間のかかる大規模タスクが一変します。

ここでは、以下の内容について詳しく解説します。

複数のサブエージェントを同時に動かす

Claude Code では複数のタスクを並列実行できます。各サブエージェントは独自のコンテキストウィンドウを持つため、互いに干渉しません。並列実行する分だけAPIの利用割合も増えるため、一度に大量に走らせるより5つ前後に絞るのが実用上のバランスです。

たとえばこういう指示を試してみてください。

「認証モジュール・DBアクセス層・APIエンドポイントのコードをそれぞれ調査して、問題点を報告してください」

Claude Code はこれを受けて3つのサブエージェントを並列で起動し、それぞれが独立して調査を進めます。順番にやった場合と比べると、処理時間は大幅に短縮されます。

大規模タスクを「分割→委譲→統合」で処理する

大きなプロジェクトでのサブエージェント活用は、次の3段階で考えると整理しやすいです。

• 分割：メインの Claude（オーケストレーター）が全体の計画を立て、並列化できるサブタスクを洗い出す
• 委譲：各サブタスクをサブエージェントに割り振り、並列実行させる
• 統合：サブエージェントから返ってきたサマリーを、オーケストレーターがまとめて最終成果物を作る

「一度に全部やって」という指示より、「まず3つのモジュールをそれぞれ調査して、結果が出たらまとめて」のように分割を明示する方がサブエージェントは動きやすいです。この「分割→委譲→統合」の流れを意識するだけで、指示の出し方が変わります。

さらに、Agent Teams（v2.1.32以降・実験的機能）を使うと複数の Claude Code セッション間での協調作業も可能になりました。2026年2月にOpus 4.6とともに公開された機能で、環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を有効にすると試せます。フロントエンドとバックエンドを別セッションで並行開発するような使い方が可能です。

Claude Codeのサブエージェント活用例3選

実際にどんな場面でサブエージェントが効くか、私が使っている例を3つ紹介します。

ここでは、以下の内容について詳しく解説します。

【活用例1】コードベース調査エージェント

「このバグの原因を全ファイルから調査して」という依頼を、そのままメイン会話でやるとコンテキストがあっという間に詰まります。調査専用のサブエージェントに委ねれば、メイン会話のコンテキストは一切消費しません。

設定は tools: [Read, Bash] のみに絞り、システムプロンプトに「ファイルを読むだけ・書き込み禁止」と明示します。調査が終わると「原因はこのファイルのこの関数にある」という簡潔なサマリーだけが返ってくるので、次の修正作業に集中できます。

大規模リポジトリでの原因調査・依存関係の確認・レガシーコードの把握など、探索系タスク全般で効果を実感しやすいため、最初に試すエージェントとしておすすめです。

【活用例2】テスト生成エージェント

実装済みのコードに対してテストケースだけを書くことに特化したエージェントです。「テスト対象のコードしか見ない・書くのはテストファイルのみ」という制約をつけることで、ハルシネーションと意図しない変更を防げます。

システムプロンプトに「Vitestでユニットテストを書く」「各関数のエッジケースを最低3つ網羅する」などプロジェクト固有のルールを書いておくと、毎回同じ品質のテストが生成されます。.claude/agents/ に置いてGitコミットすれば、チーム全員が同じテスト生成エージェントを使えます。

【活用例3】ドキュメント整備エージェント

複数のAPIエンドポイントのドキュメントを同時に生成・更新するのに使っています。エンドポイントごとにサブエージェントを並列で立ち上げ、一斉にドキュメントを生成します。10本のAPIを順番に処理するより大幅に速く終わります。

このエージェントでは model: claude-haiku-4-5 を指定しています。ドキュメント整備のような定型的なタスクはHaikuで十分な精度が出るので、コストを抑えながら大量処理できます。高精度モデルを全エージェントに使うより、タスクの性質に合わせてモデルを選ぶと費用対効果が上がります。

Claude Codeでサブエージェントを使うときの注意点3つ

サブエージェントは便利ですが、仕組みを理解せずに使うとはまりやすいポイントがあります。私が実際にやらかした経験も含めて整理します。

ここでは、以下の内容について詳しく解説します。

メイン会話のコンテキストはサブエージェントに引き継がれない

これが一番ハマりやすいポイントです。サブエージェントはまっさらな新しいコンテキストから始まります。メイン会話でClaude Codeと積み上げてきた「このプロジェクトはBunを使う」「日本語で返答して」といったルールや判断は、サブエージェントには一切引き継がれません。

対策は2つです：

• システムプロンプトに書く：エージェント定義ファイルのシステムプロンプトに、必要なルールと前提を記述する
• タスク指示に含める：「このエージェントを使ってください。プロジェクトはBunを使っています」のように、呼び出し時の指示に文脈を添える

さらに、hooksの SessionStart イベントを使ってセッション開始時に情報を自動注入する方法もあります。hooksとサブエージェントを組み合わせると、コンテキストの引き継ぎをより柔軟に設計できます。

モデル選択でコストを最適化する

frontmatterの model フィールドを指定しないと、全サブエージェントがデフォルトモデルを使います。並列で複数のサブエージェントを動かすと、コストが想定より高くなることがあります。

タスクの性質でモデルを使い分けるのが基本です：

• claude-haiku-4-5：ドキュメント生成・フォーマット整形・ファイル名変換など定型タスク
• claude-sonnet-4-6：コードレビュー・バグ原因調査・設計判断など複雑な思考が必要なタスク

どのモデルが適切か判断がつかない場合は、まず claude-haiku-4-5 で試して、品質が足りないと感じたときに上位モデルに変えるのがコストを抑えるコツです。

エージェントの暴走と無限ループへの対策

明確な完了条件を指示に入れないと、サブエージェントが際限なく作業を続けることがあります。防ぐための手順は3つです。

• toolsフィールドで権限を制限する：不要な書き込み権限を与えない。調査専用なら Read だけで十分
• 完了条件を指示に書く：「〇〇ファイルの調査が終わったら報告してください」のように終わりを明確にする
• Agent Viewでモニタリングする：v2.1.139以降の Agent View で、サブエージェントのセッション状態を一覧確認できる

よくある質問

Q：Claude Code のサブエージェントとSkillsは何が違いますか？

A：Skillsは .claude/commands/ に置くMarkdownで「スラッシュコマンドとして呼び出せるプロンプト」を定義するものです。一方、サブエージェントは独立したコンテキストで動く「専門ワーカー」です。Skillsは同じコンテキスト内で動作しますが、サブエージェントはコンテキストを分離した別プロセスで動きます。探索・並列処理・コンテキスト節約にはサブエージェント、繰り返し使うプロンプトの定型化にはSkillsと使い分けましょう。詳しくはClaude Code Skillsの使い方も参考にしてください。

Q：Claude Code サブエージェントを使うのに必要なプランは何ですか？

A：Claude Code 自体の利用には最低でもProプランへの加入が必要です。カスタムサブエージェントはClaude Codeの設定機能なので、Claude Codeが使えるプランであれば追加料金なしで利用できます。Claude Codeの始め方についてはClaude Code 使い方｜初心者向け3ステップ入門を参考にしてください。

Q：サブエージェントが/agentsに表示されません。どうすればいいですか？

A：frontmatterの構文を確認してください。--- で上下を囲んでいるか、YAMLのインデントが半角スペースで揃っているか、name フィールドが入っているかをチェックします。次にファイルの配置場所を確認します（~/.claude/agents/ または .claude/agents/）。これで解決しない場合は、Claude Code を再起動して設定ファイルを再読み込みさせてみてください。

まとめ

Claude Code サブエージェントは「コンテキスト分離」と「並列処理」の2つで、Claude Code の限界を大きく押し広げてくれます。難しそうに見えますが、やってみると .claude/agents/ に Markdown ファイルを1つ置くだけで動き出します。

最初の一歩としては、調査専用エージェントから始めるのがおすすめです。tools: [Read] だけに制限したシンプルな設定で、コードベース探索をサブエージェントに外注するところから試してみてください。うまく動いたら、モデル指定やシステムプロンプトを少しずつ育てていくと、自分のワークフローにフィットした専門エージェントが出来上がります。

サブエージェントを使い始めると、「自分が繰り返しやっている探索作業」が見えてきます。その作業を次のエージェント化の候補にしていくと、Claude Code がどんどん使いやすくなっていきます。あなたのワークフローで一番手間に感じている繰り返し作業は何でしょうか？そこから専門エージェントを1つ作ってみてください。

関連記事：Claude Code Skillsの使い方・Claude Codeでのターミナルの使い方