Claude Codeのサブエージェント機能の使い方｜開発を役割分担する方法

本記事を読めば、Claude Codeのサブエージェントで調査・レビュー・テストを役割分担でき、長時間の開発セッションでも文脈整理とレビュー品質を安定化できます。

サブエージェントは、専門的な役割を持つ別コンテキストのAIに作業を任せる仕組みです。大規模な修正ほど、担当範囲と権限を分ける設計が効きます。

AIzen株式会社は、AIエージェントを組み込んだ開発支援の知見をもとに、大規模コードベースで使いやすい設計方法を解説します。

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

Claude Codeのサブエージェントは、メイン会話とは別のコンテキストで動く専門エージェントです。調査、コードレビュー、テスト確認、デバッグなど、目的を絞った作業を任せることで、メイン会話の文脈を整理しやすくなります。大きな開発タスクを、役割ごとの小さな確認に分けることが実務での使いどころです。

サブエージェントの基本機能

サブエージェントは、専用のシステムプロンプト、利用できるツール、モデル、権限などを定義できます。Claude Code公式ドキュメントでは、name と description が必須で、tools、model、permissionMode、mcpServers などのフィールドを指定できるとされています。

たとえば、code-reviewer にはReadやGrep中心の読み取り権限を与え、品質やセキュリティ観点の指摘に集中させます。test-runner にはテスト実行に必要なBash権限を与え、変更後の確認結果をまとめさせます。役割を分けることで、メイン会話で全作業を抱え込むより判断しやすくなります。

メイン会話との役割分担

メイン会話は、目的、制約、最終判断を持つ場所です。サブエージェントは、その中の一部作業を担当します。メイン会話が「このPRを安全に確認したい」と判断し、code-reviewer が差分を読む、test-runner がテスト方針を確認する、debugger が再現条件を調べる、という分担です。

重要なのは、サブエージェントの結果をそのまま最終結論にしないことです。各エージェントは専門観点で有用な情報を返しますが、優先順位や採用判断はメイン会話と人間が行います。

別コンテキストで動くメリット

Claude Codeのサブエージェントは、通常は新しい独立したコンテキストで開始します。メイン会話の長い履歴や途中の思考を全部持ち込まないため、調査結果やレビュー結果を要約として受け取りやすくなります。

長時間セッションでは、メイン会話にログ、調査メモ、試行錯誤が溜まり、判断が重くなります。サブエージェントに自己完結した調査を任せると、メイン会話は「結果を統合する場所」として保ちやすくなります。ただし、サブエージェントは既にメイン会話で読んだファイルを自動で知っているわけではないため、依頼時に必要な前提を明確に渡します。

サブエージェントの作り方

Claude Codeのサブエージェントは、/agents で作成する方法と、.claude/agents 配下にMarkdownファイルとして定義する方法があります。チームで共有するならファイル化し、個人の試行なら /agents から始めると扱いやすいです。

/agentsでの作成手順

/agents は、Claude Code内でサブエージェントを作成・管理するための入口です。対話的に名前、説明、プロンプト、ツールなどを設定でき、作成後すぐに使える点が便利です。

初回は、汎用的なエージェントを増やすより、用途が明確な1つから始めます。たとえば、code-reviewer を作り、「変更差分を読み、重大度の高い品質・セキュリティ・テスト不足だけを指摘する」と定義します。説明文には、Claudeがいつこのエージェントへ委任すべきかを書きます。

.claude/agents配下の定義

プロジェクトで共有するサブエージェントは、.claude/agents/ 配下にMarkdownファイルとして置きます。ユーザー全体で使う場合は ~/.claude/agents/ に置く方法もあります。プロジェクト配下に置くと、リポジトリの開発ルールと一緒に管理しやすくなります。

定義ファイルは、YAML frontmatterと本文で構成します。例は次の通りです。

--- name: code-reviewer description: Reviews changed code for quality, security, and missing tests tools: Read, Glob, Grep --- You are a code reviewer. Focus on serious issues, security risks, and missing tests. Return findings with file references and severity.

このように、ファイルとして残すとレビューや変更履歴を管理できます。チームで使う場合は、サブエージェント定義もPRレビュー対象にします。

name・description・toolsの設定

name は一意な識別子です。小文字とハイフンで、code-reviewer、test-runner、debugger のように役割が分かる名前にします。description は、Claudeがそのサブエージェントを使うべき条件を書く項目です。

tools は、サブエージェントが使えるツールを制限するために重要です。省略すると多くのツールを継承する場合があるため、読み取り専用のレビュー担当にはRead、Glob、Grepだけを与えるなど、目的に合わせて絞ります。ツール権限は「便利だから広げる」ではなく「役割に必要だから許可する」で決めます。

役割別サブエージェントの設計

サブエージェントは、名前を増やすほど便利になるわけではありません。役割が重なると、どのエージェントに任せるべきか判断しづらくなります。最初は、レビュー、テスト、デバッグの3種類に絞ると実務に乗せやすくなります。

code-reviewerの役割

code-reviewer は、変更差分や関連ファイルを読み、品質・セキュリティ・保守性の観点で指摘します。見るべき観点は、認証漏れ、権限チェック、入力検証、個人情報ログ、テスト不足、例外処理、既存設計との不一致です。

レビュー担当には、編集権限を与えない設計が向いています。読み取り専用で調査し、指摘だけ返します。修正まで任せると、レビューと実装の役割が混ざり、判断が曖昧になります。レビュー結果は、重大度と根拠を添えて返すように指示します。

test-runnerの役割

test-runner は、変更後に実行すべきテストを選び、必要に応じてテストを実行し、結果をまとめる役割です。全テストを毎回実行すると時間がかかるため、対象ディレクトリ、変更ファイル、失敗ログをもとに実行範囲を絞ります。

このエージェントには、テスト実行に必要なBashやシェル権限を与えることがあります。ただし、破壊的なコマンドや外部サービスへの書き込みは許可しません。実行前に、コマンド、目的、想定時間をまとめるよう指示すると安心です。

debuggerの役割

debugger は、エラー再現、ログ確認、原因候補の整理に向いています。バグ修正では、いきなりコードを書き換えるより、再現条件、関連ログ、原因候補、最小修正案を分けることが重要です。

debugger には、読み取り、検索、テスト実行、ログ確認の権限を与えます。編集権限は、チームルールに応じて制限します。特に本番に近い環境では、実行できるコマンドを限定し、外部通信やデータ更新は承認制にします。

役割	主な目的	推奨ツール
code-reviewer	品質・セキュリティ・テスト不足の指摘	Read, Glob, Grep
test-runner	テスト選定と実行結果の整理	Read, Grep, Bash
debugger	再現条件と原因候補の整理	Read, Grep, Bash

弊社エンジニアからのコメント：

サブエージェントを導入するときは、最初に編集可能な万能エージェントを作るより、読み取り専用の code-reviewer、テスト実行だけ許可した test-runner、原因調査に集中する debugger に分けるほうが安定します。権限を分けておくと、結果を統合するときに「誰の判断か」が追いやすくなります。

サブエージェントの権限管理

サブエージェントの権限管理では、ツール、MCP、編集可否、外部通信を分けて考えます。役割ごとに許可範囲を絞ることで、調査の効率と安全性を両立できます。

読み取り専用エージェントの設計

読み取り専用エージェントは、レビューや調査に向いています。Read、Glob、Grepのような検索・閲覧ツールに限定し、WriteやEditを使わせない設計です。

読み取り専用でも、機密情報にアクセスする可能性はあります。対象リポジトリに本番 .env、秘密鍵、顧客データが含まれていないかを確認します。必要に応じて、読ませてよいディレクトリや除外対象をプロンプトに書きます。

編集権限を持つエージェントの条件

編集権限を持つサブエージェントは、役割と完了条件が明確な場合に限定します。たとえば、docs-updater がドキュメントだけを更新する、test-writer がテストファイルだけを追加する、といった範囲です。

編集権限を与える場合は、変更可能なパス、禁止ファイル、実行してよいコマンド、PR作成前の確認項目を定義します。コードレビュー担当と編集担当を同じサブエージェントにすると、自己レビューになりやすいため、チーム運用では分けるのが安全です。

MCPツール利用時の確認項目

MCPツールをサブエージェントに使わせる場合は、参照系と更新系を分けます。GitHub、チケット管理、社内DB、ドキュメント管理などへ接続できると便利ですが、外部システムへ書き込む権限を安易に渡すと、影響範囲が広がります。

確認項目は次の通りです。

• サブエージェントが使うMCPサーバー名
• 参照だけか、更新もできるか
• 認証情報の保存場所とローテーション方法
• 実行ログをどこに残すか
• 誤操作時の取り消し手順があるか

MCPは強力な連携手段ですが、サブエージェントの専門性と権限範囲を合わせることが重要です。

サブエージェントのチーム運用ルール

チームでサブエージェントを使う場合は、定義ファイル、命名、レビュー、更新ルールを揃えます。個人が自由に作ったエージェントが増えると、同じ目的の定義が重複し、結果の品質が揃いません。

調査・実装・レビューの分業

調査、実装、レビューは分けて運用します。調査エージェントは原因候補を整理し、実装担当は変更差分を作り、レビューエージェントは差分を確認します。この分業により、メイン会話は各結果を比較しやすくなります。

たとえば、大きな不具合対応では、debugger が再現条件を確認し、メイン会話が修正方針を決め、実装後に code-reviewer と test-runner が確認します。順番を決めることで、サブエージェントの結果が衝突しにくくなります。

サブエージェントの結果の統合判断

サブエージェントの結果は、必ず統合判断します。code-reviewer が「テスト不足」と言い、test-runner が「既存テストで十分」と言う場合もあります。その場合は、メイン会話で根拠を比較し、最終的に人間が採用判断をします。

統合判断では、各エージェントに同じ形式で結果を返させると扱いやすくなります。たとえば、要約、確認したファイル、指摘、重大度、未確認事項、次の推奨アクションを固定します。

チーム共有時の更新ルール

.claude/agents 配下の定義は、コードと同じようにレビューします。新規追加、ツール権限変更、MCP追加、プロンプト変更はPRで確認します。特に tools や permissionMode を広げる変更は、セキュリティ担当や開発リードが見るべきです。

AIzen株式会社では、AIエージェントをチーム開発に組み込む際、サブエージェント定義、プロジェクトルール、レビュー基準、MCP権限をセットで整備する支援を行っています。個人の便利な設定を、チームで再利用できる運用ルールへ変換することが大切です。

まとめ

Claude Codeのサブエージェント機能は、調査、レビュー、テスト、デバッグを役割分担し、長時間の開発セッションでも文脈を整理しやすくする仕組みです。

要点は3つです。

まず、/agents や .claude/agents で、name、description、tools を明確にしたサブエージェントを作ります。

次に、code-reviewer、test-runner、debugger のように役割を分け、権限を必要最小限にします。

最後に、サブエージェントの結果はメイン会話で統合し、人間が最終判断します。

AIzen株式会社では、Claude Codeを含むAIエージェント導入、開発フロー設計、権限管理、チーム共有ルールの整備を支援しています。大規模コードベースでAIを安全に分担活用したい場合は、サブエージェント設計から相談できます。