Claude Codeのサブエージェントとは？使い方やうまく動かないときの原因・対策も紹介

最終更新日:2026/06/17

Claude Codeのサブエージェント機能を使いこなせば、複雑なタスクを役割ごとに分担させて効率的に処理できるようになります。

この記事では、サブエージェントの基本的な仕組みから実際の作成手順、そしてチーム開発での安全な運用方法まで、実践的なノウハウを詳しく解説します。

特に次のような方にとって役立つ内容です。

• Claude Codeでサブエージェントを使ってタスクを並列化したい開発者
• サブエージェントの設定方法が分からず困っている方
• チームでサブエージェントを安全に共有したいプロジェクトマネージャー

この記事を読むことで、サブエージェントの作成から運用まで一通りマスターでき、開発業務の生産性を大きく向上できます。

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

Claude Codeのサブエージェントとは、特定の種類のタスクを専門的に処理させるために作成できる独立したアシスタント機能です。

メインのClaude Codeとは別に、特化した役割を持つエージェントを複数用意できるため、複雑なプロジェクトでも効率的に作業を分担できます。

サブエージェントの最大の特徴は、メインのチャットとは独立した専用のコンテキストウィンドウで動作する点にあります。

つまり、メインの会話内容に関係なく、サブエージェントは自分に与えられた指示だけに集中して処理を行います。この独立性により、次のようなメリットが得られます。

• 長時間の作業でもトークン消費を大幅に抑えられる
• メインの会話が脱線したり混乱したりするリスクを回避できる
• 複数の異なるタスクを並行して処理しやすくなる

例えば、コードレビュー専門のサブエージェント、ドキュメント作成専門のサブエージェントといった形で役割分担することで、それぞれが最適化された動作を実現できます。

メインエージェントは全体の指揮を執り、具体的な作業は各サブエージェントに委譲するという構造が可能になるのです。

サブエージェントとClaude Code Skillsの違い

サブエージェントとClaude Code Skillsは、どちらもClaude Codeで利用できる機能ですが、その役割と使い方には明確な違いがあります。サブエージェントは、特定のタスクを別のコンテキストで処理する専門アシスタントのような存在です。

一方、Claude Code Skillsは、繰り返し使う作業手順やチェックリストをClaudeに読み込ませるための指示セットとして機能します。

両者の違いをわかりやすく整理すると、以下のようになります。

• サブエージェント:独立したコンテキストで動作し、大量の情報を扱う専門タスクに適している
• Claude Code Skills:メインの会話内で参照される手順書やルール集として機能し、必要に応じてサブエージェント内でも実行できる

実際の使い分けとしては、大量のログ解析やデータ処理など、専門的で重いタスクはサブエージェントに任せるのが効果的です。

対して、コードレビューの基準やドキュメント作成のテンプレートなど、繰り返し使う手順やルールはClaude Code Skillsとして登録しておくと便利です。

このように、タスクの性質に応じて適切に使い分けることで、Claude Codeをより効率的に活用できます。

項目	サブエージェント (Sub-agents)	スキル (Agent Skills)
定義	特定の目的・システムプロンプトを持った「隔離された専門アシスタント」	メインエージェントが自動的に呼び出して使う「再利用可能なワークフロー」
コンテキスト（記憶）	メインの会話とは独立しており、親の文脈を知らない	メインの会話コンテキストを完全に共有・参照する
呼び出し方	ユーザーまたは親エージェントが明示的にタスクを委譲する	Claudeが必要だと判断したタイミングで自動的に実行される
適したタスク	コードレビュー、テスト生成、独立した大規模リサーチ	特定のコマンド実行、定型的なファイル操作、API呼び出し

Claude Codeにおけるサブエージェントの使い方

Claude Codeでサブエージェントを作成する方法は大きく分けて2つあります。

1つ目は、/agentsコマンドを使って対話形式で作成する方法です。2つ目は、Markdownファイルを直接作成してサブエージェントを定義する方法です。

初めて使う方には/agentsコマンドを使った方法をおすすめします。

/agentsコマンドを使う方法では、Claude Codeが対話形式でサブエージェントの作成をサポートしてくれます。コマンドを実行すると専用の作成画面が開き、必要な項目を順番に入力していくだけで設定が完了します。

この方法なら、Markdownの記法を覚える必要がなく、視覚的にわかりやすい画面で作業を進められます。また、/agentsで作成した定義は即時反映されるため、すぐに動作確認ができます。

一方、Markdownファイルで直接作成する方法は、より細かい制御が可能で、バージョン管理システムとの相性も良い点がメリットです。

ただし、ファイルの構造や記法を理解する必要があることに加え、手動でファイルを編集した場合はセッションの再起動が必要になります。ある程度慣れてから使うとよいでしょう。

本記事では、初めてサブエージェントを作成する方を対象に、/agentsコマンドを使った作成手順を詳しく解説していきます。次のセクションから、実際の画面操作に沿って、1つずつステップを確認していきましょう。

①/agentsコマンドでサブエージェント作成画面を開く

サブエージェントを作成するには、まずClaude Codeのチャット入力欄で「/agents」コマンドを入力します。このコマンドを実行すると、Claude CodeのUI内にサブエージェント管理用のパネルが開きます。

このパネルはターミナル（CLI）、IDE拡張（VS Code／JetBrainsなど）、デスクトップアプリ、Webブラウザ版（beta）など、Claude Codeを利用するいずれの環境でも利用できます。

管理画面には2つのタブが用意されており、それぞれ異なる役割を持っています。

• Running（実行中）：現在動作しているサブエージェントの状態を確認できます
• Library（ライブラリ）：保存済みのサブエージェント一覧を表示し、新規作成や編集が可能です

初めてサブエージェントを作成する場合は、「Library」タブに切り替えてください。タブを開くと、既存のサブエージェントが一覧表示されるとともに、「Create new agent」というボタンが表示されます。このボタンをクリックすることで、新しいサブエージェントの作成画面に進めます。

既存のサブエージェントを編集したい場合は、一覧から対象のエージェントを選択し、編集や削除も可能です。

このように、/agentsコマンドはサブエージェント管理の推奨される主要な入り口です。

②保存先スコープを選ぶ

サブエージェント作成画面を開くと、最初に保存先スコープの選択を求められます。ここでは「Personal」と「Project」の2つの選択肢が表示され、作成するサブエージェントをどこに保存するかを決定します。

まず「Personal」を選んだ場合、サブエージェントはユーザー単位のスコープに保存されます。具体的には~/.claude/agents/ディレクトリに配置され、あなたが関わるすべてのプロジェクトで個人的に使い回すことができます。例えば、自分だけが使うコードフォーマッターや、個人的な作業効率化のためのサブエージェントを作りたいときに便利です。

一方で「Project」を選択すると、サブエージェントはプロジェクト単位のスコープである.claude/agents/ディレクトリに保存されます。この保存先を選ぶ最大のメリットは、Gitなどのバージョン管理システムで管理できる点です。

プロジェクト固有のコードレビュー基準を反映したサブエージェントや、チーム共通のテスト生成ルールを組み込んだサブエージェントを作成し、チームメンバー全員で共有したい場合に適しています。

チーム開発では、このProject設定を活用することで、サブエージェントの設定変更履歴も追跡でき、チーム全体で一貫した開発支援を受けられるようになります。

③「Generate with Claude」または手動設定で内容を作成する

サブエージェントの作成画面では、内容を設定する方法として「Generate with Claude」を使った自動生成と、すべて手動で設定する方法の2つから選ぶことができます。初めてサブエージェントを作る場合や、設定内容に迷う場合は「Generate with Claude」を選ぶと便利です。

この機能を使うと、プロンプト欄に「どのようなタスクを任せたいか」を英語または日本語で具体的に入力するだけで、Claudeが適切な設定内容を自動で提案してくれます。

たとえば、「コードレビューを担当するエージェント」や「セキュリティチェックを行うエージェント」といった用途を記述すると、Claudeは以下のような要素を自動生成します。

• エージェント名（識別子）
• Description（サブエージェントの役割説明）
• システムプロンプトの土台

サブエージェント名（nameフィールド）は、code-reviewer、test-writer、security-reviewerのように、小文字とハイフンで構成された一意の識別子である必要があります。

一方、設定内容を細かくコントロールしたい場合や、既存のテンプレートがある場合は、手動設定を選んで自分ですべての項目を入力することもできます。

どちらの方法を選んでも、後から編集できるため、まずは自動生成で土台を作り、必要に応じて調整するという使い方が効率的です。

④Description・Prompt・Toolsを設定する

サブエージェントの設定では、まずDescriptionにサブエージェントの役割を簡潔に記述します。この説明文は、Claudeがメイン会話の中で「どのような場面でこのサブエージェントにタスクを自動委譲すべきか」を判断するための重要な基準となります。例えば「コードレビュー専門」や「テストコード生成担当」といった明確な役割を書くことで、適切なタイミングでサブエージェントが呼び出されるようになります。

次にPrompt欄には、サブエージェントの具体的な動作を定義するシステムプロンプトを記述します。ここでは以下のような要素を含めると効果的です。

• サブエージェントの具体的な役割と責任範囲
• タスクを実行する際の判断基準や優先順位
• 作業の手順やチェックリスト
• 出力形式やレポートの構造

Tools設定では、サブエージェントに許可する機能を選択します。読み取り、検索、コマンド実行、ファイル編集など、必要な権限だけを与えることがセキュリティ上重要です。例えばコードレビュー専門のサブエージェントであれば、Read-only toolsのみを許可し、WriteやEditの権限を制限することで、誤ってコードを変更するリスクを防ぐことができます。

このように最小権限の原則に基づいて設定することで、安全性と信頼性の高いサブエージェント運用が実現できます。

⑤モデル・色・メモリなどの追加設定を確認する

サブエージェントの基本設定が完了したら、さらに細かい動作を調整するための追加設定を確認しましょう。

まずモデル（Model）の項目では、サブエージェントが使用するClaudeのバージョンを選択できます。処理速度を重視するならhaiku、高度な推論が必要ならopus、バランスを取るならsonnetを選ぶとよいでしょう。

また、メイン会話と同じモデルを使いたい場合はinherit（継承）を選択することで、設定の手間を省けます。

次に色（Color）の項目は、タスクリストやトランスクリプト上でサブエージェントを視覚的に区別するための設定です。

red、blue、green、yellow、purple、orange、pink、cyanといった色から選択でき、複数のサブエージェントを同時に動かす場合、それぞれに異なる色を割り当てておくと、どのエージェントがどの処理を担当しているのかが一目で分かり、作業効率が大きく向上します。

さらにメモリ（Memory）の項目では、永続メモリの設定が可能です。user、project、localのいずれかを選ぶと、サブエージェントが会話をまたいでコードベースのパターンやデバッグの知見を蓄積し、次回以降の作業に活かせるようになります。

一方で、学習を永続化させたくない場合はNoneを選択することで、毎回クリーンな状態でサブエージェントを起動できます。これらの設定を適切に組み合わせることで、サブエージェントの挙動を目的に応じて最適化できるのです。

⑥保存して作成したサブエージェントを試す

設定内容を最終確認したら、画面下部の「Save」ボタンをクリックするか、キーボードで「S」キーまたは「Enter」キーを押して保存します。/agents画面で保存した場合は、Claude Codeのセッションを再起動することなく、作成したサブエージェントがすぐに利用可能な状態になります。

実際にサブエージェントを試すには、まず通常の会話の中でエージェント名を明示的に指定する方法があります。たとえば「Use the code-reviewer agent to suggest improvements for this function」のように、自然言語でサブエージェント名を含めて依頼すると、Claude Codeが該当するサブエージェントへ委譲するかを判断し、多くの場合は自動で呼び出します。

さらに確実にサブエージェントを起動したい場合は、ファイルを指定するときと同じように「@」記号を使った明示的なメンション機能が便利です。プロンプト入力欄で「@」を入力すると、利用可能なサブエージェントの一覧が表示されるので、そこから「@”code-reviewer (agent)”」のように選択することで、自動委譲に頼らず直接そのサブエージェントに処理を依頼できます。

この方法を使えば、複数のサブエージェントを使い分ける場面でも、意図した通りの動作を確実に実現できます。

Claudeでサブエージェントがうまく動かないときの原因と対処法

サブエージェントを実装する際、最もつまずきやすいのが「コンテキストの断絶」による動作不良です。メインエージェントとサブエージェントは独立した実行環境を持つため、期待通りに情報が引き継がれないケースが頻繁に発生します。

典型的な失敗パターンとして、以下のようなものがあります。

• メインエージェントで取得したファイルパスやデータがサブエージェントに渡らず、処理が途中で停止する
• サブエージェント起動時に必要なパラメータが不足し、エラーを返す
• 複数のサブエージェントを連携させたとき、前段の処理結果が後段に伝わらない

これらの問題を解決するには、サブエージェントのPrompt設定で「入力として受け取るべき情報」を明示的に定義することが重要です。たとえば「ファイルパスを必ず受け取る」「処理対象のデータ形式を指定する」といった前提条件をPromptに記載しておくと、メインエージェントがサブエージェントを呼び出す際に必要な情報を渡しやすくなります。

また、Tools設定の不足も動作不良の原因になります。サブエージェントがファイル操作を行う必要があるのにReadやWrite（必要に応じてEdit）ツールの権限が付与されていない場合、処理は実行できません。エラーメッセージを確認し、不足しているToolsを追加することで解決できます。

さらに、サブエージェント同士の連携が必要な場合は、メインエージェントが「情報の受け渡し役」として機能するよう設計する必要があります。サブエージェントAの出力をメインエージェントが一度受け取り、それをサブエージェントBへの入力として明示的に渡す流れを作ることで、連携の失敗を防げます。

メインエージェントの会話履歴が引き継がれず処理が止まるケース

サブエージェントを使っていると、「さっきのファイルを見直して」「前述のバグを直して」といった曖昧な指示を出した途端に、エラーが発生したり処理が止まったりするケースがあります。これはサブエージェントの仕様に起因する問題です。

サブエージェントは起動のたびに親会話とは独立した新しいコンテキストで開始します。親会話の履歴やその場で読んだファイル・呼び出したスキルは見えないため、メインエージェントとサブエージェントは独立した環境で動作しているのです。

ただし、サブエージェントのシステムプロンプト、委譲タスク文、CLAUDE.mdやメモリ、Gitステータス、そしてskillsフィールドで指定したスキルの本文は初期状態で読み込まれます。

この問題を回避するには、単発の指示を出す際に毎回必要な情報を明示的に渡す必要があります。サブエージェントへの受け渡しはAgentツールのプロンプトが唯一の経路です。

• 対象のファイルパスを完全な形で指定する
• 具体的なエラーログやエラーメッセージを含める
• 達成すべき要件や期待する出力を明確に記述する

こうした対策が有効です。

また、何度も繰り返し参照させたい開発ルールや前提知識がある場合は、サブエージェント定義のskillsフィールドに該当するスキルを指定しておくことで、起動時に自動でその内容をコンテキストに展開・ロードさせることができます。

この方法を使えば、毎回同じ前提情報を渡す手間を省きながら、サブエージェントに必要な知識を確実に提供できるようになります。

サブエージェント同士が情報を共有できず連携に失敗するケース

複数のサブエージェントを連携させようとして、思うように動かない経験をした方も多いのではないでしょうか。

例えば「レビュー用エージェント」にコードレビューを依頼した後、「修正まで終わったらデバッグ用エージェントに回して」と指示しても、エージェント間で情報が共有されず連携に失敗するケースがあります。

これはClaude Codeの仕様上、サブエージェントから別のサブエージェントを直接起動すること、いわゆるネスト構造が禁止されているためです。この制限は無限ネスト（nested delegation）を防ぐための安全策として設けられています。

このような連携失敗を防ぐには、親となるメインエージェントを全体の統括役として位置づけ、指示を出しては結果を回収する「Fork-Joinモデル」を意識したプロンプト設計が有効です。

• メインエージェントがレビュー用エージェントを起動し、結果を受け取る
• 受け取った結果をもとに、メインエージェントが次にデバッグ用エージェントを起動する
• 各サブエージェントは独立したタスクのみを実行し、他のエージェントを呼び出さない

こうした流れを徹底することで、チェーン状の処理が安定します。サブエージェント同士を直接つなごうとせず、必ずメインエージェントを経由させる設計を心がけてください。

なお、フォーク型サブエージェント（fork）は親会話の文脈を継承できますが、フォークから更にフォークすることはできません。

ネストが必要に見える場合は、メイン会話からサブエージェントを順次起動してチェーンするか、Skillsの活用を検討してください。

チーム開発でサブエージェントを安全に使うための運用ルール

チーム開発でサブエージェントを活用する際は、個人で自由に作成・利用するだけでなく、組織全体で安全に運用するためのルールを整備することが不可欠です。

特に複数のメンバーが同じプロジェクトに関わる環境では、サブエージェントが持つ権限や実行できる操作の範囲を明確に定義しておかないと、意図しないファイルの上書きや削除、システムへの予期せぬ変更が発生するリスクがあります。

そのため、まず権限管理の観点から以下のポイントを押さえておく必要があります。

• ファイル編集権限の範囲を明確にする
• コマンド実行の可否と対象ディレクトリを制限する
• 外部APIへのアクセス権限を必要最小限に留める

また、プロジェクト内で共有するサブエージェントについては、誰が作成・編集できるのか、どのスコープで保存するのかといった管理方法を事前に決めておくことが重要です。

さらに、サブエージェントが生成した出力結果やコードは、必ず人間が確認してからマージやデプロイを行うという確認ルールを設けることで、品質とセキュリティの両面を担保できます。

こうした運用ルールを文書化し、チーム全体で共有することが、安全で効率的なサブエージェント活用の鍵となります。

最小権限の考え方でToolsを設定する

サブエージェントを安全に運用するためには、それぞれのエージェントに必要最小限のToolsだけを許可する設計が欠かせません。

例えばコードレビューやリサーチを専門とするサブエージェントであれば、ファイルの内容を確認するだけで十分なケースが多いため、書き込み系のツールは許可しない方が安全です。

具体的には、次のような設定が推奨されます。

• Read:ファイルの内容を読み取る
• Grep:特定のキーワードでファイルを検索する
• Glob:グロブパターンに一致するファイル一覧を取得する

これらの読み取り専用ツール（”Read”、”Grep”、”Glob”など）は、サブエージェント定義のtools配列に明示的に列挙して許可します（例：[“Read”, “Grep”, “Glob”]）。こうして読み取り専用ツールに絞ることで、誤ってファイルを上書きしたり削除したりするリスクを大幅に減らせます。

一方で、WriteやEditといった編集系のツールは、実際にコードを修正するサブエージェントにのみ許可するようにしましょう。

またBashについては、git diffでの差分確認やテストスクリプトの実行など、開発フローで必要になる場面もあります。

ただし、Bashは任意コマンドを実行できるため、Write/Editを不許可にしていても、サブプロセス（例：スクリプト）経由でファイルが変更される可能性があります。必要最小限で許可し、実行コマンドを運用ポリシーで明確に制限してください。

このように必要以上に広い権限を与えないことで、チーム全体の安全性が高まり、サブエージェントが予期しない動作をするリスクを最小限に抑えられます。

サブエージェントに任せる範囲と確認ルールを決めておく

チームでサブエージェントを活用する際は、事前に任せる業務の範囲と確認ルールを明確に定めておくことが不可欠です。

具体的には、どのタスクをサブエージェントに委譲するのか、対象となるファイルやディレクトリはどこまでか、どの操作には必ず人間の承認を挟むのかといった点をチーム内で合意しておく必要があります。

サブエージェントは独自のコンテキストで作業を進め、メインの会話には結果の要約のみを返す仕組みになっているため、作業の全プロセスを細かく確認できるとは限りません。そのため、タスクの種類ごとに適切な確認ルールを設けることが重要になります。

• コードレビュー:変更内容を必ず人間が確認する
• テスト生成:生成されたテストケースの妥当性を検証する
• ログ解析:抽出された情報の正確性を確認する
• ファイル編集:編集前後の差分を必ずレビューする

このように、業務内容に応じた確認プロセスを整備しておくべきです。

特に注意が必要なのは、機密情報や顧客情報、認証情報、未公開の仕様などを含むファイルを扱う場合です。

これらのデータについては、`.claude/settings.json`のpermissions設定でdenyに登録してサブエージェントから読み取り不可とするなど、社内のAI利用ルールやセキュリティ基準に沿って明確に線引きする必要があります。

また、サブエージェントが提案したコード変更や出力結果をそのまま採用するのではなく、最終的には必ず人間がレビューして判断を下すという原則を徹底することで、安全性と品質を担保できます。

まとめ

Claude Codeのサブエージェント機能を活用することで、複雑なタスクを役割ごとに分担させ、開発効率を大幅に向上させることができます。サブエージェントの作成は/agentsコマンドから始まり、保存先スコープの選択、Description・Prompt・Toolsの設定、モデルや色などの追加設定を経て完了します。

設定の際は最小権限の原則に基づいてToolsを慎重に選び、チーム開発では任せる範囲と確認ルールを明確にしておくことが重要です。

うまく動かない場合は、メインエージェントとの会話履歴が既定では共有されない仕様や、サブエージェント同士が独立コンテキストで動作することに起因する情報共有の抜けが原因になりやすいため、適切な対処法を把握しておきましょう。サブエージェントはClaude Code Skillsとは異なり、より柔軟で高度な自動化を実現できる強力なツールです。

この機能を正しく理解し運用することで、開発プロセス全体の生産性と安全性を両立させることが可能になります。ぜひ本記事で紹介した手順と運用ルールを参考に、あなたのプロジェクトでもサブエージェントを効果的に活用してください。

アイスマイリーでは、生成AIのサービス比較と企業一覧を無料配布しています。課題や目的に応じたサービスを比較検討できますので、ぜひこの機会にお問い合わせください。