Claude Codeサブエージェント構築ガイド：YAML定義と連携の実践術

大規模プロジェクトでの開発において、単一のエージェントにすべてのタスクを委ねることは、コンテキスト（記憶容量）の圧迫と推論精度低下を招きます。本記事では、Claude Codeにおけるサブエージェントの設計手順から、Agent Teams（並列処理チーム）との使い分け、そして実戦で使えるYAML設定テンプレートまでを網羅的に解説します。

サブエージェントが必要な理由

AIエージェントにプロジェクト全体の権限を渡すのではなく、役割を分割する設計は、開発効率を最大化するための必須アプローチです。

性能維持とコスト最適化

AIモデルは一度に読み込める情報量（コンテキストウィンドウ）に制限があります。大規模プロジェクトにおいて、すべてのコードベースを一つのエージェントに読み込ませると、重要な情報が埋もれ、指示の解釈ミスが発生しやすくなります。

サブエージェント（特定の小規模タスクを専門とするAI）を活用することで、以下のメリットが得られます。

• コンテキストの軽量化: 必要なファイルのみに焦点を絞るため、入力トークンの消費を抑え、推論精度を維持できます。
• 専門性の向上: コードレビュー、テスト生成、ドキュメント作成など、特定のドメインに特化させることで出力の質が安定します。

使い分けの基準

2026年現在のClaude Code環境では、階層型と並列型の運用を使い分ける必要があります。

「タスクAが完了してからBを行う」場合はサブエージェント、「コード修正とテスト作成を同時に並行して行う」場合はAgent Teamsを構成するのが最適です。

関連記事：【残業削減】AIエージェントによる業務効率化｜成功事例と導入のコツを解説

Claude Code実装手順

サブエージェントは直感的なCLI（コマンドラインインターフェース）操作で作成可能です。

/agents コマンドによる対話的セットアップの流れ

ターミナルで /agents コマンドを実行すると、対話形式で新しいエージェントの定義を開始できます。以下のステップで進めます。

1. コマンド実行: ターミナルで /agents を入力。
2. テンプレート選択: デフォルトのボイラープレート（雛形）を選択。
3. プロンプト入力: エージェントの名前と目的を指定。
4. ディレクトリ生成: .claude/agents/ 配下に定義ファイルが自動生成されます。

YAML定義ファイルの書き方

生成されたYAMLファイルは、エージェントの「脳」を定義するマニュアルです。主な設定項目を以下に示します。

---
name: code-reviewer
description: プルリクエスト用のコードレビューを専門に行うエージェント
tools: Read, Glob
disallowedTools: Bash
---
コードを分析し、バグの可能性とコーディング規約違反を指摘してください。
結果は必ずMarkdown形式で出力すること。

※定義ファイルは純粋なYAMLではなくMarkdownファイル（.md）です。YAMLフロントマターの後にシステムプロンプトを記述します。

関連記事：【実験的機能】Claude Code teamsを活用して開発はどう変わる？AI同士が自律協調する仕組みを解説

スコープ管理と実行権限

セキュリティを確保するため、エージェントの行動範囲を適切に制限することが重要です。

スコープ制御のレベル

• プロジェクトレベル: .claude/agents/ に格納することで、そのプロジェクト固有のコンテキストを共有します。
• ユーザーレベル: ホームディレクトリの ~/.claude/agents/ に設定することで、マシン内の全プロジェクトで共通のアシスタントとして活用可能です。

サンドボックス化の設定

不必要なファイル読み込みや外部通信を防ぐため、disallowedTools（使用禁止ツール）を設定し、エージェントをサンドボックス（隔離環境）に閉じ込めます。

• 機密情報を含むディレクトリへのアクセスを制限する。
• 本番環境のデータベース操作ツールを disallowedTools に追加する。

関連記事：【導入検討】Claude Codeの導入で開発スピードはどう変わる？AIエージェント時代に不可欠な3つの承認ルール

エージェント定義テンプレート

開発現場で頻出するタスクを3つのパターンで用意しました。そのままコピーして活用してください。

コードレビュー特化型

---
name: pr-reviewer
description: git diffを読み取り、論理的な欠陥を指摘する
tools: Read, Glob
---
変更差分のみを読み取り、循環的複雑度が高い箇所を重点的に指摘してください。

テスト生成型

---
name: test-generator
description: 既存コードに対するユニットテストを生成する
tools: Read, Glob, Write
---
対象ファイルに対して、Jest形式のテストコードを作成してください。既存のテストカバレッジを維持すること。

ドキュメント作成型

---
name: doc-writer
description: 関数仕様の自動ドキュメント生成
tools: Read, Glob, Write
---
JSDocコメントを解析し、APIリファレンス用のMarkdownを生成してください。

自動デリゲーションのコツ

親エージェントがサブエージェントを適切に判断して呼び出すには、description 欄が鍵となります。ここに「どのような状況で呼び出されるべきか」を具体的に明記することで、デリゲーション（権限委譲）の精度が向上します。

関連記事：【図解】Claude Codeエージェント活用術｜プログラミング不要で「指示から実行」までを完結させる方法

カスタムエージェントの開発

標準のYAML設定では不十分な場合、Python SDKを用いて高度な拡張が可能です。

Python SDKの連携

カスタムツールをSDKで記述することで、社内のSlack APIやJiraと直接連携させることができます。

# 独自ツールの統合例
class JiraTool:
    def execute(self, issue_id):
        # 社内APIとの通信ロジック
        return response

最適化とエラー処理

エージェント間の通信ロスを防ぐため、以下の設計を推奨します。

• ステートレス（状態を持たない）設計: 通信のたびに必要なコンテキストのみを渡す。
• タイムアウト設定: 応答が遅いエージェントをスキップするエラーハンドリングを必ず実装する。

関連記事：Claude Code並列実行の活用法｜/batchコマンドと環境分離の仕組み

まとめ

Claude Codeを活用したサブエージェント構築のポイントをまとめます。

• コンテキスト分離: 役割を分担することで、トークン効率と推論精度を最大化する。
• 構造的理解: .claude/agents/ 配下のYAMLで役割と権限を明確に定義する。
• 柔軟な設計: 逐次処理にはサブエージェント、並列処理にはAgent Teamsを使い分ける。
• セキュリティ: allowlist でエージェントの行動を制限し、サンドボックス化を徹底する。

まずは小規模なタスクからサブエージェントを定義し、プロジェクトの自動化を今すぐ始めてみてください。

無料ニュースレター

AIの大事な変化を、見逃さない。

海外の最新AIニュースも、公式発表から日本語に要約してお届け。
「毎日忙しいけど、AIの最先端は知っておきたい」——そんな人のための1通です。

無料で読みはじめる → 🎁読者限定｜AI活用ガイド進呈

運営：AIエージェント専門メディア編集部｜登録無料・いつでも解除可能