Claude Code のサブエージェントとは何か個人開発から始める設計と運用ガイド

サブエージェントとは何か：メインの会話と切り離された専門アシスタント

Claude Codeのサブエージェントは、メインの会話とは別の、独立したコンテキストウィンドウ（会話が保持する文脈情報の枠）上で動く、特定タスクに特化したアシスタントです。普段のやり取りが行われている「本体」の会話とは切り離された場所で作業し、必要な結果だけを本体に返します。

なぜこの仕組みが必要かというと、調査や検証のように大量の情報を読み込む作業を本体の会話でそのまま行うと、コンテキストが長くなり、本題に関係のないログや中間結果で埋まってしまうからです。サブエージェントに調査だけを切り出せば、本体の会話は要点だけを受け取り、見通しの良い状態を保てます。

この「作業の場を分けることで本体の文脈を圧迫しない」という考え方を、以降は「コンテキスト分離」と呼びます。この記事内で繰り返し出てくる概念なので、ここで一度だけ定義しておき、次節以降は前提として扱います。なお、この節はあくまで仕組みの定義を扱うものです。呼び出され方によって挙動がどう変わるかは、後段の「起動のされ方」で改めて説明します。

組み込みサブエージェントを知る

Claude Codeには、あらかじめ用意されているサブエージェントがいくつか存在します。例えば、コードベースの調査に使われるものや、計画立案に使われるもの、特定の用途に限定されない汎用的なものなどが挙げられます。それぞれ、コードを読むだけの調査作業や、複雑なタスクの手順を組み立てる作業など、場面に応じて自動的に呼び出されることがあるとされています。

ただし、名称や役割分担、どのような条件で自動的に起動するのかという細かい仕様は、バージョンによって変わる可能性があります。正確な最新の仕様は、公式ドキュメントの該当ページで確認することをおすすめします。この記事では、組み込みのサブエージェントが存在すること、そしてそれらが用途ごとに役割を持っていることまでを押さえておけば十分です。

起動のされ方：新規コンテキストか、会話を引き継ぐか

サブエージェントの呼び出され方には、大きく分けて、まったく新しい文脈から作業を始めるパターンと、直前までの会話のやり取りをある程度引き継いだ状態で始まるパターンがあるとされています。前節で説明した「コンテキスト分離」を踏まえたうえで、この節ではその分離が実際の運用でどう現れるか、つまり呼ばれ方によって見える情報や処理コストがどう変わるかという点に絞って扱います。

新規に文脈を始めるパターンは、余計な情報を持ち込まずにタスクへ集中させたいときに向いています。一方、会話を引き継ぐパターンは、それまでのやり取りの流れを踏まえた判断が必要な場面に向いていると考えられます。どちらが適しているかは、そのサブエージェントに任せたい作業が「独立して完結する調査」なのか「文脈の続きとしての作業」なのかが判断基準になります。

カスタムサブエージェントの作り方

自分の用途に合わせたサブエージェントは、大きく二つの方法で作成できます。

一つ目は /agents コマンドを使う方法です。対話形式で質問に答えていくことで、名前や役割、使わせたいツールなどを順に決めていけます。設定ファイルの書式を覚えていなくても始められるのが利点です。

二つ目は、.claude/agents/ ディレクトリの下にMarkdownファイルを手動で作成する方法です。ファイルの先頭にフロントマター（YAML形式のメタ情報）を書き、その下に実際の指示文を書きます。主なフィールドは次のとおりです。

---
name: research-assistant
description: コードベースや外部ドキュメントの調査を専門に行う。実装や修正は行わず、調査結果の要約だけを返す。
tools: Read, Grep, Glob
model: sonnet
---

あなたはコードベースの調査を専門とするアシスタントです。
与えられた質問に対して、関連するファイルとコードの箇所を特定し、
根拠となる箇所を明示したうえで要点を簡潔にまとめて報告してください。
自分で実装やファイルの変更は行わないでください。

ここで特に重要なのが description の書き方です。Claudeは会話の中で「今のタスクをどのサブエージェントに任せるべきか」を、この description の内容をもとに判断します。「調査を行う」のような曖昧な書き方だと、似た役割の別のサブエージェントと区別がつかず、意図した場面で呼び出されなかったり、逆に不要な場面で呼び出されたりすることがあります。「何を対象に」「何をする」「何をしない」まで具体的に書いておくと、判断材料として機能しやすくなります。

役割別の設計例

複数のサブエージェントを組み合わせる場合、役割を明確に分けて設計するとわかりやすくなります。よく見られる分け方として、次のようなものがあります。

コードの調査だけを行う「調査専門」のサブエージェント
変更の実装だけを行う「実装専門」のサブエージェント
実装後の差分を確認する「レビュー専門」のサブエージェント
テストの実行結果を確認し、失敗の原因を切り分ける「デバッグ専門」のサブエージェント

このように役割を分けておくと、各サブエージェントの指示文を短く保てますし、description も具体的に書きやすくなります。計画・生成・評価のように、さらに細かく段階を分けて設計するやり方も存在しますが、段階を増やすほど設計とメンテナンスの手間も増えます。まずは二つか三つの役割分担から試し、必要になった段階で細分化を検討する進め方が現実的です。

権限とモデル選択の設計基準

サブエージェントを設計する際は、ツール権限とモデルの二つを決める必要があります。この節では、実際に起きた失敗ではなく、決める際の考え方に絞って説明します。

ツール権限については、調査だけを行わせるサブエージェントには読み取り系のツールのみを与え、ファイルの編集や実行系のツールは持たせない、という判断が基本になります。逆に、実装まで任せたいサブエージェントには編集権限を与えますが、その場合は指示文の中で「変更してよい範囲」を明示しておくと、意図しない箇所への変更を防ぎやすくなります。

モデル選択については、タスクの複雑さと、精度・処理コストのバランスで判断します。定型的な調査や単純なチェック作業には軽量なモデルを、複雑な設計判断や難易度の高い実装が必要な作業には高性能なモデルを割り当てる、という考え方が基本の指針になります。どちらを選ぶか迷う場合は、まず軽量なモデルで試し、結果の精度に不満が出た時点で切り替える、という小さく始めて様子を見るやり方も選べます。

よくある失敗とアンチパターン

前節の基準を踏まえたうえで、実際に起こりやすい失敗のパターンを見ておきます。

権限を絞りすぎて、サブエージェントが必要な作業を完了できず、途中で止まってしまう
逆に権限を広く与えすぎて、意図しないファイルの変更や削除が起きるリスクが高まる
description が曖昧なために、想定していた場面で呼び出されなかったり、関係のない場面で呼び出されたりする
役割分担を細かくしすぎて段数が増え、処理コストが想定以上に膨らむ

これらはいずれも、設計時の基準が曖昧なまま作成を進めてしまうことで起きやすくなります。新しいサブエージェントを作った後は、想定した場面で実際に呼び出されるか、権限の範囲が過不足ないかを一度試してから使い始めると、こうした失敗を減らせます。

個人利用からチームで共有するときの注意点

自分一人で使っている間は気にならなくても、チームで共有し始めると別の論点が出てきます。ここでは要点だけを挙げ、詳しい運用ルールの作り方は別の記事に譲ります。

.claude/agents/ をリポジトリに含め、他のコードと同じようにバージョン管理する
サブエージェントの名前は役割が一目でわかる命名にし、チーム内で命名規則をそろえる
変更を加えたら、変更内容と理由を簡潔に記録しておく
権限が広いサブエージェントについては、共有前にレビューする運用を決めておく

より詳細な権限設計や情報の扱い方、チーム全体でのルール策定については、運用ルールの作り方を扱った記事で扱っています。

Skillsや通常のCLAUDE.md運用との使い分け

Claude Codeには、目的の異なるいくつかの仕組みがあります。整理すると次のようになります。

仕組み	性質	向いている用途
その場での指示	一時的、その会話限り	一度きりの細かい指示や質問
CLAUDE.md	恒久的、プロジェクト全体に常時適用	プロジェクト共通のルールや前提知識
サブエージェント	コンテキストを分離した専門アシスタント	特定の作業を切り出して任せたいとき

CLAUDE.mdの書き方や運用の考え方は、CLAUDE.mdの書き方を扱った記事で詳しく説明しています。プロジェクト全体に常に適用したいルールはCLAUDE.mdに、特定の作業だけを切り出して任せたい場合はサブエージェントに、というように役割で使い分けると迷いにくくなります。

まとめ

サブエージェントは、コンテキストを分離した専門アシスタントです。組み込みのものを知ったうえで、.claude/agents/ に自分用のものを定義し、権限とモデルを設計してから、チームでの共有へと広げていく、という順番で進めると無理がありません。

まだCLAUDE.mdやClaude Codeの基本操作に不安がある場合は、Claude Codeの入門記事から読み進めるのもよい選択です。体系的に学び直したい場合は、研修の選び方を扱った記事も参考になります。

自分のプロジェクトに合わせたサブエージェントの設計や、CLAUDE.md・運用ルールまで含めて一緒に整理したい場合は、コーチングという選択肢も用意しています。学習を独力で進めるか、伴走してもらいながら進めるかは、必要に応じて選んでください。