【ITニュース解説】Claude Code subagents: how to create and use them (with examples)

Claude Codeのサブエージェントは、あなたがソフトウェア開発のプロジェクトマネージャーになったかのように、複雑なタスクを効率的にこなすための強力な仕組みだ。これは、あなたのメインとなるClaudeの作業セッションとは別に、専用の役割と能力を持つ「代理人」を雇うようなものだと考えると分かりやすい。システムエンジニアを目指す初心者にとって、このようなAIの活用方法は、将来の業務効率化や新しい開発手法を理解する上で非常に役立つだろう。

サブエージェントとは、メインのClaudeセッションから特定のタスクを依頼されると、独自の思考空間、つまり「コンテキストウィンドウ」を開いて作業を始める、独立したClaudeのインスタンスを指す。この代理人は、あなたからの指示（システムプロンプト）や、使用を許可された専用のツールセットを持って、依頼されたタスクに集中する。例えば、大量のログファイルを分析したり、何十ものテスト結果を読み込んだりといった、メインセッションで行うには情報量が多すぎる作業を肩代わりさせることができる。さらに重要なのは、メインセッションが作成した成果物を、サブエージェントが「第三者の目線」でレビューできる点だ。これは、人間が自分の書いたコードを客観的にレビューするのが難しいのと同じで、AIにも作業者とレビュアーの役割を分担させることで、より質の高い結果を得られる可能性がある。サブエージェントは、与えられたタスクの最終的な要約だけをメインセッションに報告するため、メインセッションは常にクリーンな状態を保ち、不要な情報で溢れることがない。

サブエージェントの作成方法は比較的シンプルだ。通常はMarkdown形式のファイルに、YAMLフロントマターと呼ばれる設定情報を記述して作成する。このファイルは、.claude/agents/ディレクトリに置けば、そのリポジトリで作業する全員が利用できるようになるし、~/.claude/agents/に置けば、あなたのすべてのプロジェクトで利用可能になる。同じ名前のエージェントが両方に存在する場合は、プロジェクト固有の設定が優先される仕組みだ。このファイルは自分で書くこともできるが、どんなエージェントが欲しいかをClaudeに説明して、代わりに作成してもらうことも可能だ。一度作成したエージェントファイルに変更を加えると、Claude Codeは数秒でその変更を反映するが、新しいエージェントフォルダを作成した場合は、セッションの再起動が必要になる場合がある。

サブエージェントの設定ファイルには、いくつかの重要な項目がある。nameはエージェントを識別するユニークな名前で、呼び出す際に使用するため、簡潔で分かりやすい名前をつけることが推奨される。descriptionは、どのようなタスクをこのエージェントに任せるべきかをClaudeに伝えるための説明文だ。これは、メインセッションがタスクを自動的にサブエージェントに委譲する際の判断基準となるため、そのエージェントの役割を具体的に記述することが重要だ。toolsは、そのサブエージェントが使用を許可されるツールのリストで、例えばRead（ファイルを読み込む）、Glob（パターンに一致するファイルを検索する）、Grep（ファイル内を検索する）といったものがある。このリストを指定しない場合、そのエージェントは利用可能なすべてのツールを継承してしまうため、特にレビューエージェントのように「何かを変更すべきではない」場合には、必要最低限のツールに制限することが望ましい。また、modelでは、そのエージェントが使用するAIモデルを指定できる。例えば、複雑な推論が必要な場合は高性能なモデルを、ルーチン的なチェックにはより安価なモデルを選択するといった使い分けが可能だ。

サブエージェントの使い方は二通りある。一つは「自動委譲」で、メインセッションでの会話内容がサブエージェントのdescriptionに合致した場合、Claudeが自律的にそのタスクをサブエージェントに渡す。もう一つは「明示的委譲」で、ユーザーが直接「〇〇というサブエージェントを使ってこの作業をしてほしい」と指示したり、@を入力してリストからエージェントを選択したりする方法だ。特定のサブエージェントをセッション全体で使いたい場合は、Claude Codeを起動する際に特定のフラグを指定することもできる。

ここで重要なのは、サブエージェントが「フレッシュなコンテキスト」を持つという点だ。サブエージェントは、メインセッションでのこれまでの会話履歴や、メインセッションがすでに読み込んだファイルの内容を一切知らない。サブエージェントは、あなたからの指示（システムプロンプト）、メインセッションが作成したタスク委譲メッセージ、そして基本的な環境情報のみを受け取って作業を開始する。このため、サブエージェントがタスクを遂行するために毎回必要となる情報（何をチェックすべきか、失敗の定義、どのような形式で結果を返すかなど）は、サブエージェントの定義ファイル内、つまりそのエージェントのプロンプト部分に明確に記述しておく必要がある。また、サブエージェントからの返答は、最終的な要約のみがメインセッションに戻ることを意識し、簡潔で固定された形式を求めるべきだ。例えば、レビュー結果を表形式で返してもらうように指示すれば、メインセッションが受け取る情報量を大幅に抑え、トークン消費の無駄を防ぐことができる。

具体的な利用例として、ショート動画の制作プロセスにおける品質チェックが挙げられる。ここでは、3つの異なる役割を持つレビューサブエージェントが活躍する。まずstory-readerは、動画の企画書（spec.json）を読み込み、初めて動画を見る人の視点でストーリーが魅力的か、矛盾がないかを評価する。このエージェントはReadツールのみを使い、ストーリーの構成要素（フック、展開、結末）が適切かをチェックし、結果をPASS/FAILで報告する。次にstills-reviewerは、制作されたストーリーボードの静止画（stills）が企画書の内容と一致しているか、画面内の重要な要素が安全な表示エリアに収まっているか、文字が読めるかなどをレビューする。このエージェントはRead, Glob, Grepといったツールに限定され、画像ファイルの内容を直接変更する権限は持たない。そして最後にfile-qaは、完成した動画ファイルを技術的な観点から品質保証する。例えば、動画の解像度が正しいか、フレームレートが適切か、再生時間が指定された範囲内かといった項目をチェックする。このエージェントはBashツールを使ってffprobeのようなコマンドを実行し、動画ファイルのメタデータを分析する。この例のように、各エージェントが必要最小限のツールと権限を持つことで、意図しない変更を防ぎ、特定のタスクに特化させることができる。これらの独立したエージェントは、それぞれの作業段階で並行して実行できるため、開発者は複数の複雑なチェック作業を同時に進め、効率的に問題点を特定できる。

サブエージェントと似た概念に「スキル」があるが、両者には明確な違いがある。スキルは、メインセッションがタスクを遂行する際に参照する具体的な手順やスクリプト、参照ファイルのセットだ。これは「仕事のやり方」を定義するもので、必要に応じてメインセッションにロードされる。一方、サブエージェントは、それ自体が独立した作業者であり、独自のコンテキストを持つ。大量の情報を処理する作業を分離したり、複数のチェックを並行して実行したり、あるいはメインセッションが行った作業を客観的にレビューしたりする際に利用する。両者を組み合わせることも可能で、例えばメインセッションがスキルを使って成果物を作成し、それをサブエージェントがレビューするといったワークフローが考えられる。

システムエンジニアがサブエージェントを利用する際に陥りやすい間違いもいくつかある。一つは、すべてのサブエージェントに無制限のツール、特にファイル書き込み権限を与えてしまうことだ。レビューエージェントが意図せずファイルを変更してしまうリスクを避けるため、権限は厳しく制限すべきである。二つ目は、非常に小さな、数行で終わるようなタスクにサブエージェントを使ってしまうことだ。サブエージェントは起動時に独自のコンテキストを構築するため、ある程度のオーバーヘッドが発生する。そのため、迅速な修正が必要な小さな作業は、メインセッションで行う方が効率的だ。三つ目は、サブエージェントがメインセッションのこれまでの会話内容を覚えていると期待することだ。前述の通り、サブエージェントは独立したコンテキストを持つため、必要な情報はタスクの委譲メッセージやエージェントファイル自体に含める必要がある。そして最後に、エージェントのdescriptionを長くしすぎることだ。descriptionはメインセッションのコンテキストの一部として常に読み込まれるため、トリガーに必要な情報に絞り、詳細な指示はエージェントのプロンプト本体に記述することが推奨される。

これらの点を理解し、適切にサブエージェントを活用することで、システム開発における複雑なタスクの管理や、品質保証のプロセスを大幅に改善できる可能性を秘めている。これは、システムエンジニアを目指すあなたが今後直面するであろう、より大規模で効率的な開発ワークフローを構築するための重要な一歩となるだろう。