サブエージェント

サブエージェントは、Cursorのエージェントがタスクを委任できる特化型のAIアシスタントです。各サブエージェントは独自のコンテキストウィンドウで動作し、特定の種類の作業を処理して結果を親エージェントに返します。サブエージェントを使用すると、複雑なタスクを分解し、作業を並列化し、メインの会話のコンテキストを維持できます。

サブエージェントは、エディター、CLI、Cloud Agentsで使用できます。

サブエージェントの仕組み

エージェントは、複雑なタスクに直面するとサブエージェントを自動的に起動できます。サブエージェントは必要なコンテキストをすべて含むプロンプトを受け取り、自律的に作業して、結果を含む最終メッセージを返します。

サブエージェントは、クリーンなコンテキストで開始します。以前の会話履歴にはアクセスできないため、親エージェントが関連情報をプロンプトに含めます。

フォアグラウンドとバックグラウンド

サブエージェントは、次の 2 つのモードのいずれかで実行されます。

組み込みサブエージェント

Cursor には、コンテキストを大量に必要とする操作を自動で処理する組み込みサブエージェントが 3 つあります。これらのサブエージェントは、コンテキストウィンドウの上限に達したエージェント会話を分析して設計されました。

これらのサブエージェントがある理由

この3つの操作には共通点があります。ノイズの多い中間出力を生成し、専用のプロンプトやツールが有効で、多くのコンテキストを消費する可能性があります。これらをサブエージェントとして実行することで、いくつかの問題を解決できます。

• コンテキストの分離 — 中間出力はサブエージェント内に留まり、親エージェントには最終的な要約のみが渡されます。
• モデルの柔軟性 — Explore サブエージェントはデフォルトで高速なモデルを使用します。これにより、メインエージェントで1回検索するのと同じ時間で、10件の並列検索を実行できます。
• 専用設定 — 各サブエージェントには、特定のタスクに合わせて調整されたプロンプトとツールへのアクセスが用意されています。
• コスト効率 — 高速なモデルは低コストです。トークン消費の多い処理を適切なモデルを選んだサブエージェントに分離することで、全体的なコストを削減できます。

これらのサブエージェントを設定する必要はありません。エージェント が必要に応じて自動的に使用します。

サブエージェントを使用する場面

クイックスタート

エージェント は、必要に応じて自動的にサブエージェントを使用します。エージェント に依頼して、カスタムサブエージェントを作成することもできます。

より細かく制御するには、プロジェクトディレクトリまたはユーザーディレクトリにカスタムサブエージェントを手動で作成します。

カスタムサブエージェント

カスタムサブエージェントを定義して、専門知識を組み込み、チームの標準を徹底し、反復的なワークフローを自動化できます。

ファイルの場所

同名のサブエージェントがある場合は、プロジェクトのサブエージェントが優先されます。同名のサブエージェントが複数の場所にある場合は、.cursor/ が .claude/ や .codex/ より優先されます。

ファイル形式

各サブエージェントは、YAMLフロントマターを含むMarkdownファイルです。

---name: security-auditordescription: Security specialist. Use when implementing auth, payments, or handling sensitive data.model: inheritreadonly: true---You are a security expert auditing code for vulnerabilities.When invoked:1. Identify security-sensitive code paths2. Check for common vulnerabilities (injection, XSS, auth bypass)3. Verify secrets are not hardcoded4. Review input validation and sanitizationReport findings by severity:- Critical (must fix before deploy)- High (fix soon)- Medium (address when possible)

設定フィールド

モデル設定

model フィールドで、サブエージェントが使用するモデルを指定します。選択肢は 2 つあります。

サブエージェントに親と同じ推論能力が必要な場合は、inherit を選択します。親が使用するモデルにかかわらず、特定のモデルの機能が必要な場合は、特定のモデル ID を使用します。

モデルパラメータ

モデル ID の末尾に角括弧を付けると、速度、推論の深さ、コンテキストウィンドウなど、モデルごとのオプションを設定できます。オプションは id=value 形式で指定し、複数のオプションはカンマで区切ります。

利用可能なオプションはモデルによって異なり、SDK のモデルパラメータと同じ id=value 形式で指定します。

---name: plannerdescription: Plans complex changes before implementation.model: claude-opus-5[effort=high]---Break the task into a clear, ordered implementation plan.

設定したモデルが使用されない場合

以下のいずれかに該当する場合を除き、Cursor はサブエージェントのフロントマターの model フィールドを使用します。

• チーム管理者による制限 — 組織の管理者が指定したモデルをブロックしています。
• 従来の Max Mode 設定 — 従来のリクエストベースプランでは、そのモデルに Max Mode が必要ですが、有効になっていません。
• プランの制限 — 現在のプランではそのモデルを利用できません。

このような場合、Cursor は互換性のあるモデルに切り替えます。想定外のモデルの挙動が見られる場合は、プランとモデルの設定を確認してください。

---name: code-reviewerdescription: Reviews code for correctness and style.model: inherit---Review the code changes for bugs, style issues, and edge cases.

---name: search-agentdescription: Searches the codebase for relevant files and symbols.model: inherit---Search the codebase and return relevant file paths and code snippets.

---name: reasoning-agentdescription: Handles complex architectural decisions.model: gpt-5.6-sol---Analyze the architecture and recommend changes with detailed reasoning.

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

自動委任

エージェントは、次の要素に基づいてタスクを自動的に委任します。

• タスクの複雑さと範囲
• プロジェクト内のカスタムサブエージェントの説明
• 現在のコンテキストと利用可能なツール

説明フィールドに「積極的に使用する」や「常に使用する」といったフレーズを含めると、自動委任が促されます。

明示的な呼び出し

プロンプトで/name構文を使って、特定のサブエージェントを指定します。

> /verifier confirm the auth flow is complete> /debugger investigate this error> /security-auditor review the payment module

サブエージェントを自然にメンションして呼び出すこともできます。

> 検証サブエージェントを使用して、認証フローが完了していることを確認する> デバッガーサブエージェントにこのエラーを調査させる> セキュリティ監査サブエージェントで支払いモジュールをレビューする

並列実行

複数のサブエージェントを同時に起動して、スループットを最大化します。

> API の変更を確認し、ドキュメントを並行して更新する

エージェントが1つのメッセージで複数のTask ツール呼び出しを行うため、サブエージェントは同時に実行されます。

クラウドサブエージェント

ローカルのエージェントセッションから、専用の VM とブランチで実行されるクラウドサブエージェントに作業を委任できます。長時間実行される作業や並列作業をクラウドで行っている間も、local workspace はクリーンな状態を保ち、快適に操作できます。親エージェントは中断されることなく、ローカルまたはクラウドで実行を継続します。クラウドサブエージェントは、Cursor desktop app の Agents Window から実行できます。

/in-cloud でクラウドサブエージェントを開始する

/in-cloud と入力すると、次に送信するタスクがクラウドサブエージェントとして実行されます。タスク用の専用 VM とブランチが起動されます。

CI の修正、問題の調査、ローカルで作業を続けながらのコードベースの探索など、時間のかかる作業や並行作業を分離するのに役立ちます。

/babysit でPRを見守る

/babysit またはクイックアクションのピルをクリックすると、クラウドサブエージェントにプルリクエストを見守らせることができます。クラウドエージェントはリモートで繰り返し作業し、ローカルセッションを占有することなく、PRをマージ可能な状態に整えます。

クラウドサブエージェントは、リポジトリ用に設定された環境を使用し、他のCloud Agentsと同じモデルおよび機能に関するルールに従います。クラウドVMで実行されるため、MCPサーバーはローカルセッションではなく、cursor.com/agents のチーム設定に基づいて使用されます。

サブエージェントの再開

サブエージェントを再開すると、以前の会話を続けられます。複数回の呼び出しにまたがる長時間実行タスクに役立ちます。

サブエージェントを実行するたびにエージェント ID が返されます。この ID を渡すと、コンテキストをすべて保持したままサブエージェントを再開できます。

> エージェント abc123 を再開し、残りのテスト失敗を分析する

よくあるパターン

検証エージェント

検証エージェントは、報告された作業が実際に完了しているかを独立して検証します。これにより、AI がタスクを完了とマークしていても、実装が不完全だったり動作しなかったりする一般的な問題に対処できます。

---name: verifierdescription: Validates completed work. Use after tasks are marked done to confirm implementations are functional.---You are a skeptical validator. Your job is to verify that work claimed as complete actually works.When invoked:1. Identify what was claimed to be completed2. Check that the implementation exists and is functional3. Run relevant tests or verification steps4. Look for edge cases that may have been missedBe thorough and skeptical. Report:- What was verified and passed- What was claimed but incomplete or broken- Specific issues that need to be addressedDo not accept claims at face value. Test everything.

このパターンは次の場合に役立ちます。

• チケットを完了としてマークする前に、機能がエンドツーエンドで動作することを検証する
• 実装が不完全な機能を検出する
• テストファイルが存在するだけでなく、テストが実際に成功することを確認する

オーケストレーター パターン

複雑なワークフローでは、親エージェントが複数の専門サブエージェントを順に連携させることができます。

1. プランナーが要件を分析し、技術的なプランを作成します
2. 実装担当者がプランに基づいて機能を作ります
3. 検証担当者が実装が要件を満たしていることを確認します

各引き継ぎでは構造化された出力が渡されるため、次のエージェントは必要なコンテキストを明確に把握できます。

サブエージェントの例

デバッガー

---name: debuggerdescription: Debugging specialist for errors and test failures. Use when encountering issues.---You are an expert debugger specializing in root cause analysis.When invoked:1. Capture error message and stack trace2. Identify reproduction steps3. Isolate the failure location4. Implement minimal fix5. Verify solution worksFor each issue, provide:- Root cause explanation- Evidence supporting the diagnosis- Specific code fix- Testing approachFocus on fixing the underlying issue, not symptoms.

テストランナー

---name: test-runnerdescription: テスト自動化のエキスパート。テストを実行し、失敗を修正するために積極的に使用してください。---あなたはテスト自動化のエキスパートです。コードの変更を検出したら、適切なテストを積極的に実行してください。テストが失敗した場合：1. 失敗の出力を分析する2. 根本原因を特定する3. テストの意図を保持したまま問題を修正する4. 再実行して検証するテスト結果の報告には以下を含めてください：- 合格／不合格のテスト数- 失敗の要約- 問題を修正するために行った変更

ベストプラクティス

• 役割を絞ったサブエージェントを作成する — 各サブエージェントには、明確に定義された単一の責務を持たせます。汎用的な「ヘルパー」エージェントは避けてください。
• 説明文を充実させる — description フィールドは、エージェント がサブエージェントに委任するタイミングを決定します。時間をかけて内容を磨きましょう。プロンプトを作成して、適切なサブエージェントが呼び出されるか確認してください。
• プロンプトは簡潔にする — 長くまとまりのないプロンプトは、焦点をぼやけさせます。具体的かつ直接的に記述してください。
• サブエージェントをバージョン管理に追加する — .cursor/agents/ をリポジトリにコミットし、チーム全体で活用できるようにします。
• エージェント が生成したエージェントから始める — エージェント を使って初期設定を下書きし、その後カスタマイズします。
• ファイル出力にはフックを使用する — サブエージェントに構造化された出力ファイルを生成させる必要がある場合は、フック を使用して結果を一貫して処理・保存することを検討してください。

避けるべきアンチパターン

• 曖昧な説明 — 「一般的なタスクに使用」では、いつ委任すべきかエージェントに伝わりません。具体的に記述してください: 「OAuth プロバイダーを使用した認証フローを実装する場合に使用。」
• 長すぎるプロンプト — 2,000語のプロンプトを与えても、サブエージェントが賢くなるわけではありません。動作が遅くなり、管理も難しくなります。
• スラッシュコマンドとの重複 — タスクが単一目的でコンテキストの分離が不要な場合は、代わりにスキルまたはコマンドを使用してください。
• サブエージェントが多すぎる — まずは用途を絞ったサブエージェントを2～3個作成してください。明確に異なるユースケースがある場合にのみ追加してください。

サブエージェントの管理

サブエージェントの作成

サブエージェントを作成する最も簡単な方法は、エージェント に作成を依頼することです。

また、.cursor/agents/ (プロジェクト) または ~/.cursor/agents/ (ユーザー) に Markdown ファイルを追加して、手動でサブエージェントを作成することもできます。

サブエージェントを表示する

エージェントは、利用可能なツールとしてすべてのカスタムサブエージェントを含みます。プロジェクト内の .cursor/agents/ ディレクトリを確認すると、設定されているサブエージェントを確認できます。

パフォーマンスとコスト

サブエージェントにはトレードオフがあります。これらを理解することで、使用すべき場面を判断できます。

トークンとコストに関する考慮事項

• サブエージェントはそれぞれ独立してトークンを消費します — 各サブエージェントには独自のコンテキストウィンドウとトークン使用量があります。5つのサブエージェントを並列実行すると、単一のエージェントの約5倍のトークンを消費します。
• オーバーヘッドを考慮してください — 短時間で完了する単純なタスクでは、メインエージェントの方が速いことがよくあります。サブエージェントは、複雑な作業、長時間にわたる作業、並列作業で力を発揮します。
• サブエージェントの方が遅くなる場合があります — 利点は速度ではなく、コンテキストの分離です。単純なタスクを行うサブエージェントは、毎回新たに開始するため、メインエージェントより遅くなる場合があります。

FAQ