Claude Code のサブエージェント入門：コンテキストを守る委譲の設計

大きなタスクを Claude Code に任せると、探索結果やログ、大量のファイル内容でメイン会話が埋め尽くされがちです。サブエージェント（subagents）は、そうした作業を独立したコンテキストで処理し、結果の要約だけをメイン会話に返す仕組みです。本記事では公式ドキュメントに基づいて、配置・フロントマター・呼び出しの仕組みを実務目線で整理します。

本記事は Claude Code の公式ドキュメント（Anthropic）を参照し、当社が日本語でまとめたものです。仕様はバージョンにより変わる場合があります。最新かつ正確な情報は記事末尾の一次資料でご確認ください。

1. サブエージェントとは何か

サブエージェントは、特定の種類のタスクを処理する専用のAIアシスタントです。公式ドキュメントによれば、各サブエージェントは独自のコンテキストウィンドウ・カスタムシステムプロンプト・限定されたツールアクセス・独立した権限を持って動作します。Claude がサブエージェントの説明に一致するタスクに出会うと委譲し、サブエージェントは独立して作業して結果を返します。

メリットは主に次の点です。

• コンテキストの保護：探索や実装の副作用をメイン会話から切り離す。
• 制約の強制：使えるツールを限定できる。
• 設定の再利用：ユーザー単位のサブエージェントをプロジェクト横断で使える。
• 挙動の専門化：特定領域向けの集中したシステムプロンプトを与えられる。
• コスト管理：Haiku のような高速・低コストのモデルにタスクを回せる。

2. どこにファイルを置くか（配置とスコープ）

サブエージェントは YAMLフロントマター付きのMarkdownファイルで定義します。ファイルの場所によって「誰が使えるか」が決まります。

• .claude/agents/ — 現在のプロジェクト向け。バージョン管理にコミットしてチームで共有・改善できます。
• ~/.claude/agents/ — 全プロジェクトで使える個人用サブエージェント。

同じ name のサブエージェントが複数ある場合、より優先度の高い場所（プロジェクト側）のものが使われます。ディレクトリは再帰的に走査されるため、agents/review/ のようにサブフォルダで整理してもかまいません（識別は name フィールドのみで行われます）。

3. フロントマターの書き方

フロントマターがサブエージェントのメタデータと設定を定義し、本文がシステムプロンプトになります。必須は name と description の2つだけです。次は読み取り専用のコードレビュー担当を作る例です。

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: コード品質とベストプラクティスをレビューする。コード変更後に使う。
tools: Read, Glob, Grep
model: sonnet
---

あなたはコードレビューの専門家です。可読性・保守性・
明らかなバグの観点で変更を確認し、具体的な指摘を返してください。
ファイルの書き換えは行いません。

主なフロントマターのフィールドは次のとおりです。

• name（必須）— サブエージェントの識別子。ツリー全体で一意にします。
• description（必須）— いつ使うべきか。Claude はこの説明を見て委譲を判断します。
• tools — 使用を許可するツールの許可リスト。上の例では書き込み系やMCPツールを与えていません。
• model — 使うモデル（例：sonnet、haiku）。探索など軽い作業は安価なモデルに回せます。

4. どう呼び出されるか（自動委譲）

Claude は各サブエージェントの description を手がかりに、タスクが一致したときへ自動的に委譲します。だからこそ、説明文に「どんなときに使うか」を具体的に書くことが最も重要です。~/.claude/agents/ と .claude/agents/ はファイルの追加・編集を数秒で検知し、次の委譲から更新後の定義が使われます（多くの場合、再起動は不要です）。

なお /agents コマンドの挙動はバージョンで変わっています。新しめのバージョンでは、対話式の作成ウィザードは廃止され、「Claude に頼むか .claude/agents/ を直接編集する」よう案内が表示されます。

5. 実務での使いどころ

サブエージェントが特に効くのは、メイン会話に残す必要のない大量の中間出力が発生する作業です。

• コード探索 — 「どこにこの処理がある？」を調べさせ、結論だけ受け取る。
• 調査・リサーチ — 大量のファイルやログを読ませ、要約を返させる。
• レビュー — 変更後にコードレビュー専用エージェントへ委譲する。

これは、当社が別記事で紹介した Simon Willison 氏の「エージェントループの設計」の考え方とも噛み合います。役割ごとに小さなループ（サブエージェント）を用意し、メインの文脈を汚さずに回す——という設計です。