カスタムClaudeコードサブエージェントの作り方 (設定ガイド)

あらゆる単一のAIコーディングセッションには、コンテキストウィンドウという限界があります。一度の会話で大がかりなリファクタリング、3ラウンドのテスト出力、コードレビューを詰め込むと、エージェントは話の筋を見失い始めます。Claude Codeのサブエージェントがその解決策です。一つのエージェントがすべてを一つのコンテキストでやりくりするのではなく、それぞれ独自のコンテキストウィンドウ、独自の指示、独自のツール権限を持つ、特化型ワーカーを立ち上げます。彼らは一つの仕事をして結果を返し、メインスレッドをきれいに保ちます。 これは実践的な構築ガイドです。コンフィグファイルとしてカスタムサブエージェントを作成する方法、各フロントマターフィールドの機能、Claudeがどのようにデリゲートを決定するか、そして、あるエージェントがコードをレビューし、別のエージェントが並行してテストを記述する実用的なセットアップを配線する方法について説明します。最初に概念的な概要が必要な場合は、「Claude Codeサブエージェントとは何か、そしてそれがなぜ重要なのか」に関する記事が基本的な部分をカバーしています。ここでは、サブエージェントの構築に焦点を当て、テストサブエージェントを信頼できる検証ステップに変えるAPIテストの視点に注目します。

TL;DR

Claude Codeサブエージェントは、.claude/agents/内にYAMLフロントマターを持つMarkdownファイルを作成することで作成します。必要なのは、name、Claudeがいつデリゲートするかを伝えるdescription、オプションのtools許可リスト、およびオプションのmodelです。ファイルの本体がサブエージェントのシステムプロンプトになります。各サブエージェントは、独自のツールを持つ独自のコンテキストウィンドウで実行されるため、コンテキストの分離、並列処理、および専門化が実現します。Claudeは説明に基づいて自動的にデリゲートするか、名前でサブエージェントを呼び出します。公式リファレンスはClaude Codeサブエージェントのドキュメントです。

60秒でわかるサブエージェント

サブエージェントは、メインのClaude Codeエージェントがタスクを渡す、別のエージェントインスタンスです。メインエージェントがリードエンジニアであり、サブエージェントはメインエージェントが呼び出すスペシャリストです。スペシャリストは、独自の会話で、独自のコンテキストウィンドウとシステムプロンプトを使用して作業し、結果のみを返します。これらを構成する価値がある3つの特性を挙げます。 * 独自のコンテキストウィンドウ。 サブエージェントは、与えられたタスクのみで新たに開始されるため、メインスレッドがその中間作業でいっぱいになることはありません。 * カスタムシステムプロンプト。 どのように動作するかを形作ることができます。セキュリティ上の欠陥を探すレビューア、あなたの規約に従うテストライターなど。 * 構成可能なツール。 各サブエージェントに必要なツールのみを付与します。これにより、レビューアは書き込みができず、テストランナーはシェルアクセスを最小限に抑えることができます。 これが概念的な基礎です。概念的な概要では、「なぜ」についてさらに深く掘り下げています。このガイドの残りの部分は、サブエージェントを構築することに焦点を当てています。これは、個々のタスクのレベルで適用されるClaude Codeエージェントハーネスの背後にあるのと同じ原則です。

サブエージェントを使用する理由

理由は3つあり、それらが複合的に作用します。 コンテキストの分離。 長時間のセッションは、コンテキストウィンドウがいっぱいになるとパフォーマンスが低下します。ファイルの読み込み、テストの実行、あらゆる脱線が予算を消費し、集中力を薄めます。大きなタスクをサブエージェントに委任すると、そのすべての作業がサブエージェントのコンテキストに保持され、メインのコンテキストには残りません。メインエージェントは、50,000トークンもの中間ノイズではなく、クリーンな要約を受け取ります。この分離はコストレバーでもあり、肥大化したコンテキストを毎回引きずり回す必要がないためです。エージェントのトークンコストを削減する方法に関する私たちのメモは、経済性に踏み込んでいます。 並列処理。 独立したタスクは、順次実行する必要はありません。メインエージェントは、複数のサブエージェントを同時にディスパッチできます。あるモジュールをレビューしながら、別のモジュールをテストし、さらに別のモジュールを文書化するといった具合です。実行時間は、合計時間ではなく、最も遅い単一タスクの時間に短縮されます。Claude Codeの動的ワークフローは、これを限界まで押し進め、単一のセッションから数百の並列サブエージェントをファンアウトさせます。 専門化。 一般的なエージェントは、あらゆることをうまくこなしますが、何かに非常に優れているわけではありません。厳密なシステムプロンプトと適切なツールを備えたサブエージェントは、一つのことに非常に優れています。敵対的なレビューアは、一般的なレビューアが差分を一瞥するよりも多くのバグを見つけます。あなたの表明スタイルを知っているテストライターは、実際に保持するテストを作成します。あなたは、過負荷になった一人のゼネラリストではなく、少人数のスペシャリストチームを構築するのです。

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

サブエージェントはプレーンなMarkdownファイルです。プロジェクトレベルのものは.claude/agents/に、個人的なものは~/.claude/agents/に配置します。各ファイルにはYAMLフロントマターと、サブエージェントのシステムプロンプトとなる本体が含まれます。 以下はコードレビュアーです。 ```markdown --- name: code-reviewer description: バグ、セキュリティ問題、規約違反についてコード変更をレビューします。コードの記述または編集後に使用します。 tools: Read, Grep, Glob model: sonnet --- あなたはシニアコードレビュアーです。差分またはファイルセットが与えられた場合： 1. 正確性のバグ、セキュリティホール、見落とされたエッジケースを探します。 2. コードがプロジェクトの既存の規約に合致しているか確認します。 3. 信頼性の高い問題のみを、深刻度順に報告します。 具体的に記述してください。ファイルと行を引用してください。安易に承認しないでください。 ``` フロントマターフィールド: * name — それを呼び出すために使用する識別子。 * description — これは重要なフィールドです。Claudeはこれを読んで、いつ自動的に委任するかを決定します。曖昧なラベルではなく、明確なトリガー（「コード作成後に使用」）として記述してください。 * tools — 許可リスト。省略するとメインエージェントのツールを継承します。制限する場合は特定のツールをリストアップします。コードを記述できないレビューアは、誤ってコードを変更することはありません。 * model — オプションでモデルを固定します。機械的なサブエージェントにはより安価で高速なモデルを、難しい推論にはより強力なモデルを使用します。 本体はシステムプロンプトです。ここに専門化が宿るので、新入社員に説明するように記述してください。何をするか、何を優先するか、何を避けるか。プロジェクトのdesign.mdまたはAGENTS.mdと組み合わせることで、サブエージェントにすべてのファイルで繰り返すことなく規約を伝えることができます。

サブエージェントの呼び出し方

サブエージェントが実行される方法は2つあります。 自動委任。 Claudeは利用可能なすべてのサブエージェントのdescriptionフィールドを読み取り、タスクが一致した場合に自動的に委任します。ファイルを編集し終えると、メインエージェントは指示されなくても変更点をcode-reviewerに渡すことがあります。これは、descriptionに「コード作成後に使用」と書かれているためです。適切なdescriptionは適切な委任を促進します。 明示的な呼び出し。 直接名前で呼び出すこともできます。「オーダーモジュールの変更についてcode-reviewerサブエージェントを使用せよ。」これは、委任を偶然に任せたくない場合に特定のスペシャリストを強制的に使用する方法です。 いずれの方法でも、サブエージェントは独自のコンテキストで実行され、作業を行い、結果をメインスレッドに返します。ハンドオフが発生するのを確認でき、どの程度の詳細が表示されるかを設定できます。サブエージェントを決定論的で反復可能なシーケンスに連鎖させるには、スラッシュコマンドとSDKがアドホックなプロンプトよりも多くの制御を提供します。Claude Codeの概要では、設定インターフェースについて説明しています。

サブエージェント vs. エージェント SDK vs. 動的ワークフロー

これらは重複するため、それぞれの使いどころを説明します。

サブエージェントは、セッション内での対話的なオプションです。Claude Codeで作業していて、1つか2つのスペシャリストが必要な場合に使用します。人間がいない状態でスケジュール通りに実行されるプログラム的なループが必要な場合は、Claude Agent SDKに移行し、オーケストレーションを自分で記述します。ホストされたオプションと独自実装を比較検討している場合は、マネージドエージェントとAgent SDKの比較がトレードオフを詳しく説明しています。これら3つは競合するものではなく、対話型から完全に自動化されたものへの梯子の段差のようなものです。

実例：並行レビューとテスト作成

これらを組み合わせます。メインエージェントが新しいオーダーのエンドポイントを実装したとします。レビューとテストが必要ですが、これらを順番に行う理由は何もありません。 2つのサブエージェントを定義します。上記のcode-reviewerと、テストライターです。 ```markdown --- name: api-test-writer description: 新規または変更されたエンドポイントのAPIテストケースを記述します。エンドポイントが実装された後に使用します。 tools: Read, Grep, Write, Bash model: sonnet --- あなたはプロジェクトのOpenAPI仕様に対してAPIテストを記述します。 1. 仕様とエンドポイントの実装を読み込みます。 2. 成功、検証エラー、認証をカバーするテストを記述します。 3. ステータスコードをアサートし、レスポンスボディをスキーマに対して検証します。 4. スイートを実行し、合否とその理由を報告します。 ``` これでメインエージェントは両方を同時にディスパッチします。レビューアが差分を読み、テストライターが仕様を読み、カバレッジを記述します。2人のスペシャリスト、2つの隔離されたコンテキストが並行して実行されます。メインスレッドはきれいに保たれ、レビューレポートとテスト結果という2つの要約が返されます。 このテスト結果こそが、これを信頼できるものにする部分です。APIスイートを実行するサブエージェントは検証ゲートであり、エンドポイントが「できたように見える」かどうかではなく、「実際に機能する」かどうかを決定的にチェックします。これは、コーディングエージェントループの中心的な考え方です。エージェント自身の自信は重要ではなく、ゲートの判断が重要です。実際のAPIテストプラットフォームに対してテストサブエージェントを配線すると、フィードバックはより鮮明になります。Apidogを使用しているチームは、サブエージェントをApidogテストシナリオに向け、すべてのレスポンスがスキーマ検証されるようにし、エージェントのライブエンドポイント呼び出しをApidog AIエージェントデバッガー経由でルーティングすることで、人間テスターと同じようにリクエストを検査します。同じセットアップをループでラップすれば、Claudeワークフローで構築した、あなたなしで実行される自動ワークフローが完成します。すぐにスキーマ認識テストゲートが必要な場合は、Apidogをダウンロードしてください。

ベストプラクティス

サブエージェントを混沌とさせず、有用なものにするためのいくつかの習慣。 * サブエージェントあたり1つの責任。 レビューアはレビューする。テスターはテストする。何でも屋のサブエージェントを作らないでください。それは単なるメインエージェントに余分なステップが加わっただけです。 * 委任のための説明文を書く。 descriptionフィールドは、Claudeがサブエージェントを呼び出すタイミングを決定する方法です。タイトルではなく、明確なトリガーとして記述してください。「コードの編集後にバグをレビューするために使用する」は「コードレビューア」よりも優れています。 * 最小特権を付与する。 各サブエージェントが必要とするツールのみをリストアップしてください。書き込みアクセス権を持たないレビューアは、レビューしているものを変更できません。これは、無人で実行される場合に特に重要です。 * ジョブごとに適切なモデルを固定する。 機械的なサブエージェントは、より高速で安価なモデルで実行できます。難しい推論を行うサブエージェントには、最も強力なモデルを温存してください。これにより、速度とコストの両方を制御できます。 * 構造化された結果を返す。 サブエージェントに一貫した形式（判決、問題のリスト、合否）で報告するように依頼してください。構造化された出力は、メインエージェントにとっても、あなたにとっても、アクションを起こしやすいものです。 * 過度なネストを避ける。 サブエージェントがサブエージェントを呼び出し、さらにそれがサブエージェントを呼び出すような構成は、追跡が困難でコストがかかります。階層は浅く保ちましょう。 これらは、エージェントワークフローツール配線でカバーした配線パターンを反映しており、サブエージェントが2つであろうと20であろうと当てはまります。

サブエージェントを使用すべき時（とそうでない時）

サブエージェントはツールであり、デフォルトではありません。いつスキップするかを知ることで、セットアップを高速かつ安価に保つことができます。 タスクが範囲が限定的で、独立しており、ノイズが多い場合にサブエージェントを使用してください。コードレビューは範囲が限定的（明確な終わりがある）、独立（メインスレッドの実行状態を必要としない）、ノイズが多い（メインコンテキストを詰まらせたくない多くの中間読み込みを生成する）です。テストスイートの作成、バグの再現、セキュリティ問題に対するモジュールの監査も同様です。これらは完璧な委任です。作業を隔離し、判定結果を得ます。 タスクが小さい、密結合している、またはメインの作業と順次実行される場合は、サブエージェントをスキップしてください。変数の名前変更、1行のバグ修正、またはメインエージェントがすでに必要なコンテキストを把握している場合は、ハンドオフしてもメリットはありません。そこでサブエージェントを起動すると、何の利益もなく遅延とコンテキストの往復が増えるだけです。メインエージェントがサブエージェントに説明するために会話の半分を説明しなければならない場合は、メインスレッドに留めておいてください。 経験則：段落で説明できるほど自己完結しており、並行して実行する価値がある作業は委任します。レビューとテストを行う新しいエンドポイントは該当します。誤字の修正は該当しません。多くの並行サブエージェントにスケールするにつれて、動的ワークフローのオーケストレーションパターンが引き継がれますが、同じ判断が適用されます。独立した作業は並列化し、結合された作業は一緒に保ちます。

よくある間違い

* 曖昧な説明。 descriptionが単なるラベルだと、期待したときに自動委任が実行されません。使用トリガーとして記述してください。 * 肥大化した1つのサブエージェント。 すべてのジョブを1つのサブエージェントに詰め込むと、専門化のメリットが失われます。責任ごとに分割してください。 * デフォルトですべてのツールを継承。 toolsを未設定のままにすると、サブエージェントはメインエージェントが持つすべてのものを取得します。信頼できる作業には問題ありませんが、自動化されたものにはリスクがあります。意図的に許可リストを作成してください。 * 検証サブエージェントがない。 テストゲートのないレビュー・ビルドのセットアップでは、見た目は正しいがエッジケースで壊れるコードが出荷されます。必ずテストを実際に実行するサブエージェントを含めてください。 * サブエージェントをSDKのように扱う。 サブエージェントはモデルによってディスパッチされ、セッション内で動作します。決定論的なスケジュールされた制御フローが必要な場合は、それはエージェントSDKの仕事であり、サブエージェントの山ではありません。 これらを正しく理解すれば、適切にスコープされた少数のサブエージェントが、Claude Codeを忙しい一人のアシスタントから、小さく集中的なチームへと変貌させます。Anthropicの「効果的なエージェントの構築」は、より広い視点から、モデル中心の構造がより大きなプロンプトよりも優れていることを主張しています。

よくある質問

Claude Codeサブエージェントとは何ですか？ メインのClaude Codeエージェントがタスクを委任する、別のエージェントインスタンスです。各サブエージェントには、独自のコンテキストウィンドウ、カスタムシステムプロンプト、構成可能なツールのセットがあります。特定のタスクを実行し、結果を返し、メインの会話をクリーンに保ち、スペシャリストを並行して実行できるようにします。 Claude Codeサブエージェントはどのように作成しますか？ .claude/agents/（プロジェクト）または~/.claude/agents/（個人）にMarkdownファイルを作成します。name、description、オプションのtools、オプションのmodelを含むYAMLフロントマターを追加し、本体にシステムプロンプトを記述します。descriptionは、Claudeにいつ自動的にタスクを委任するかを伝えます。 Claudeはどのサブエージェントを使用するかをどのように決定しますか？ 利用可能な各サブエージェントのdescriptionフィールドを読み取り、タスクが一致した場合に自動的に委任します。「コードレビューアサブエージェントを使用する」のように、名前で明示的に呼び出すこともできます。明確でトリガー形式の説明は、自動委任を信頼性の高いものにします。 サブエージェントとClaude Agent SDKの違いは何ですか？ サブエージェントはセッション内であり、モデルによってディスパッチされます。Claude Codeで作業しているときに、スペシャリストを呼び出すようなものです。Agent SDKはプログラマティックであり、決定論的または無人での実行のためにコードで制御フローを記述します。対話的な専門化にはサブエージェントを、スケジュールされたループにはSDKを使用します。 サブエージェントは並行して実行できますか？ はい、できます。メインエージェントは、独立したタスクのために複数のサブエージェントを同時にディスパッチできるため、レビュー、テスト、ドキュメント作成が順番ではなく並行して行われます。大規模なファンアウトの場合、Claude Codeの動的ワークフローは、これを1つのセッションで多くの並列サブエージェントに拡張します。 サブエージェントはAPIテストにどのように役立ちますか？ OpenAPI仕様に対してAPIテストを記述し実行するサブエージェントを定義します。これは、エンドポイントが「完了したように見える」かどうかだけでなく、「実際に機能する」かどうかをチェックする検証ゲートになります。Apidogのようなプラットフォームにポイントすることで、フィードバックはスキーマ認識になり、すべてのレスポンスが契約に対して検証されます。

まとめ

Claude Codeサブエージェントは、一つのコンテキストウィンドウではすべてを保持できないという問題を解決します。各タスクに独自のコンテキスト、指示、ツールを与えることで、単一の過負荷なエージェントを、並行して作業し、クリーンな報告を行う少人数の専門家チームに置き換えることができます。セットアップはMarkdownファイルだけで、その見返りは集中力、スピード、そして適切なジョブに適切なモデルを割り当てる能力です。 まずはレビュアーとテスターの2つから始めましょう。Claudeが自動的に委任できるように具体的な説明を書き、それぞれに必要なツールのみを許可し、テスターを実際の検証ゲートにするためにAPIスイートにポイントしてください。エンドポイントに関わることなら何でも、Apidogはそのゲートに検証するためのスキーマを提供します。Apidogをダウンロードして、差分を読む前にテストサブエージェントにコードが機能することを証明させましょう。