メインコンテンツまでスキップ

Cursor でのサブエージェントの設定と使用

Cursor サブエージェントガイド

Cursor のサブエージェントを使用すると、複雑なタスクを並列または順次で実行できる小さな専門化されたユニットに分解できます。プランナーエージェントが全体のタスクをオーケストレーションし、サブエージェントは独自のモデル、スコープ、セキュリティ境界で特定のサブタスクを処理します。このガイドは、モデル選択からセキュリティ設定まですべてをカバーし、堅牢なマルチエージェントワークフローの構築を支援します。

サブエージェントの理解​

サブエージェントとは？​

サブエージェントは、プランナーエージェントの指揮の下で動作する独立したエージェントインスタンスです。各サブエージェントは独自の以下を持ちます：

  • モデル: 異なるタスクタイプに対する異なる AI モデル
  • スコープ: 制限されたファイルおよびディレクトリアクセス
  • セキュリティ境界: 実行できるアクションの制限
  • コンテキスト: 干渉を防ぐための分離されたコンテキストウィンドウ

プランナーエージェントは複雑なタスクを分解し、サブタスクをサブエージェントに割り当て、結果を収集し、最終出力を総合します。このアーキテクチャは、人間のチームが専門家間で作業を分割する方法を反映しています。

サブエージェントを使用するタイミング​

サブエージェントは、単一のエージェントではタスクの広さや複雑さに対処するのが困難なシナリオで威力を発揮します：

  • 複数のモジュールにまたがる大規模なリファクタリング
  • フロントエンドとバックエンドの両方の変更が必要な機能の実装
  • テストの実行、バグの修正、ドキュメントの更新の同時実行
  • 複数のリポジトリにまたがるコードレビュー
  • コード変更の並列生成と検証
ヒント

シンプルな単一ファイルタスクの場合、サブエージェントアーキテクチャはメリットなくオーバーヘッドを追加します。タスクが自然に独立したまたは半独立したサブタスクに分割される場合にサブエージェントを使用してください。タスクを一文で説明できる場合、おそらくサブエージェントは不要です。

モデル選択​

プランナーとサブエージェントのモデル選択​

サブエージェントセットアップで最も重要な決定の一つは、プランナーにどのモデルを割り当て、サブエージェントにどのモデルを割り当てるかです。異なるモデルには異なる強み、コスト、速度特性があります。

利用可能なモデル​

モデル強み速度コスト最適な用途
cursor-proバランスの取れた推論と速度中中プランナー、一般タスク
cursor-fast高速な反復、シンプルなタスク高速低シンプルなサブエージェント
cursor-max深い推論、複雑なロジック遅い高複雑なサブエージェント
cursor-think拡張推論、アーキテクチャ最遅最高複雑なタスクのプランナー

設定​

Cursor 設定またはプロジェクト設定でモデル割り当てを設定します：

// settings.json で
{
  "cursor.subagents.enabled": true,
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.defaultModel": "cursor-fast",
  "cursor.subagents.maxConcurrent": 4,
  "cursor.subagents.timeout": 300000
}

サブエージェントごとのモデル設定​

タスクに基づいて異なるモデルを異なるサブエージェントに割り当てることができます：

# .cursor/subagents/config.yaml
planner:
  model: cursor-pro
  description: "Orchestrates the overall task and synthesizes results"
  maxSubagents: 5

subagents:
  - name: "frontend-agent"
    model: cursor-max
    description: "Handles React component changes"
    scope:
      files: ["src/components/**", "src/pages/**"]
    tools: ["read", "write", "edit"]

  - name: "backend-agent"
    model: cursor-max
    description: "Handles API and server logic"
    scope:
      files: ["src/api/**", "src/server/**", "src/models/**"]
    tools: ["read", "write", "edit", "terminal"]

  - name: "test-agent"
    model: cursor-fast
    description: "Writes and runs tests"
    scope:
      files: ["test/**", "src/**/*.test.*"]
    tools: ["read", "write", "terminal"]

  - name: "docs-agent"
    model: cursor-fast
    description: "Updates documentation"
    scope:
      files: ["docs/**", "README.md", "CHANGELOG.md"]
    tools: ["read", "write"]
ヒント

複雑なロジックや重要なコードパスを処理するサブエージェントには cursor-max などの強力なモデルを使用してください。フォーマット、ドキュメント、定義済みコマンドの実行などのシンプルなタスクには cursor-fast を使用します。これによりコストと品質のバランスが効果的に取れます。

モデル選択のベストプラクティス​

モデル割り当てを決定する際は、以下のガイドラインを考慮してください：

  1. プランナーには強力な推論が必要: プランナーはタスク全体を理解し、分解し、結果を総合する必要があります。プランナーに cursor-pro または cursor-think を使用してください。
  2. 複雑さにモデルを一致させる: シンプルなファイル編集に cursor-max は不要です。深い理解を必要とするタスクに高価なモデルを予約してください。
  3. コンテキストウィンドウを考慮: 複雑なサブタスクにはより大きなコンテキストウィンドウが必要な場合があります。cursor-max は cursor-fast より多くのコンテキストをサポートします。
  4. コスト意識のスケーリング: 4 つの cursor-fast サブエージェントを実行する方が、1 つの cursor-max エージェントより安価です。ただし品質が重要な場合は、重要なサブタスクに優れたモデルを投資してください。
// コスト最適化設定
{
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-fast",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-fast",
    "docs-agent": "cursor-fast"
  }
}

// 品質最適化設定
{
  "cursor.subagents.plannerModel": "cursor-think",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-max",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-max",
    "docs-agent": "cursor-fast"
  }
}
警告

すべてのサブエージェントに高価なモデルを使用すると、プランのトークン予算を急速に消費する可能性があります。Cursor: Show Token Usage コマンドで使用量を監視してください。上限に近づいている場合、非重要なサブエージェントを cursor-fast にダウングレードしてください。

スコープ制御​

ファイルアクセス制限​

スコープ制御は、各サブエージェントがアクセスできるファイルとディレクトリを決定します。これはセキュリティ対策であり、サブエージェントが意図しない変更を行うのを防ぐための品質改善でもあります。

ファイルスコープの設定​

# .cursor/subagents/scopes.yaml
subagents:
  - name: "auth-module-agent"
    scope:
      # このエージェントが読み取りと変更できるファイル
      files:
        include:
          - "src/auth/**"
          - "src/middleware/auth.ts"
          - "config/auth.json"
        exclude:
          - "src/auth/legacy/**"
      # このエージェントがリストして探索できるディレクトリ
      directories:
        - "src/auth"
        - "src/middleware"
      # エージェントがスコープ外のファイルにアクセスできるかどうか
      strictMode: true

strictMode が true の場合、サブエージェントは宣言されたスコープ外のファイルを読み取り、リスト、または変更できません。これはほとんどのユースケースで推奨される設定です。

警告

ユーザーから、スコープ制限が設定されている場合でも、エージェントが開いたディレクトリ外のファイルを探索することがあると報告されています。これは通常以下の場合に発生します：

  1. strictMode 設定が明示的に true に設定されていない（デフォルトは false）
  2. サブエージェントがターミナルコマンドを使用してファイルにアクセスする（ファイルスコープチェックをバイパス）
  3. スコープ設定が相対パスを使用し、予想とは異なる方法で解決される
  4. サブエージェントがプランナーのより広いスコープを継承する

これを防ぐには、常に strictMode: true を設定し、ターミナルツールアクセスも制限してください。以下のセキュリティ境界セクションを参照してください。

一般的なスコープパターン​

モジュールベースのスコープ: エージェントを特定のモジュールに制限：

- name: "user-module-agent"
  scope:
    files:
      include: ["src/modules/user/**"]
    strictMode: true

レイヤーベースのスコープ: エージェントを特定のアーキテクチャレイヤーに制限：

- name: "api-layer-agent"
  scope:
    files:
      include:
        - "src/api/routes/**"
        - "src/api/controllers/**"
        - "src/api/middleware/**"
    strictMode: true

読み取り専用スコープ: 読み取りは許可するが変更は不可：

- name: "code-review-agent"
  scope:
    files:
      include: ["src/**"]
    tools: ["read"]  # 書き込みまたは編集ツールなし
    strictMode: true

共有ファイルスコープ: 複数のエージェントが共有設定ファイルにアクセス可能：

- name: "config-aware-agent"
  scope:
    files:
      include:
        - "src/features/feature-a/**"
        - "src/shared/config.ts"  # 共有設定ファイル
        - "src/shared/types.ts"   # 共有タイプ定義
    strictMode: true

セキュリティ境界​

ツール制限​

各サブエージェントは特定のツールに制限できます。これにより、サブエージェントが実行すべきでないアクションを実行するのを防ぎます。

# .cursor/subagents/security.yaml
subagents:
  - name: "read-only-analyzer"
    description: "Analyzes code without modifying anything"
    tools:
      - read
    # 書き込み、編集、ターミナルツールなし
    scope:
      files:
        include: ["src/**"]
      strictMode: true

  - name: "test-runner"
    description: "Runs tests and reports results"
    tools:
      - read
      - terminal
    scope:
      files:
        include: ["test/**", "src/**"]
      strictMode: true
    terminal:
      allowedCommands:
        - "npm test"
        - "npm run test:unit"
        - "npm run test:integration"
      blockedCommands:
        - "rm"
        - "git push"
        - "npm publish"

  - name: "file-editor"
    description: "Edits source files only"
    tools:
      - read
      - write
      - edit
    # ターミナルアクセスなし
    scope:
      files:
        include: ["src/**"]
      strictMode: true
ヒント

ターミナルアクセスの allowedCommands と blockedCommands 設定は、二重のセキュリティレイヤーを提供します。サブエージェントが何らかの方法でターミナルアクセスを得たとしても、明示的に承認されたコマンドのみを実行できます。これは CI/CD パイプラインや自動化環境でエージェントを実行する場合に特に重要です。

サブエージェント間の干渉の防止​

サブエージェントは独立して動作する必要があります。相互に干渉するのを防ぐには：

  1. 重複しないファイルスコープ: サブエージェント間で同じファイルに対する重複する書き込みアクセスがないことを確認
  2. 個別のブランチ: 各サブエージェントを個別の Git ブランチで作業させることを検討
  3. 段階的実行: サブエージェントが互いの出力に依存する場合、順次実行を使用
# 例: 依存関係のある順次実行
execution:
  strategy: sequential
  steps:
    - agent: "schema-agent"
      description: "Generate database schema first"
      scope:
        files:
          include: ["src/models/**", "migrations/**"]
      tools: ["read", "write", "edit"]

    - agent: "api-agent"
      description: "Build API endpoints based on schema"
      dependsOn: "schema-agent"
      scope:
        files:
          include: ["src/api/**"]
      tools: ["read", "write", "edit"]

    - agent: "test-agent"
      description: "Write tests for the new API"
      dependsOn: "api-agent"
      scope:
        files:
          include: ["test/**"]
      tools: ["read", "write", "terminal"]
警告

2 つのサブエージェントが同時に同じファイルに書き込むと、プランナーが自動的に解決できないマージコンフリクトが発生します。書き込み可能なサブエージェントのファイルスコープが重複しないことを常に確認してください。実行前に Cursor: Validate Subagent Scopes コマンドで重複をチェックしてください。

環境変数アクセス​

各サブエージェントがアクセスできる環境変数を制御します：

- name: "deploy-agent"
  scope:
    env:
      allow:
        - "DEPLOY_TARGET"
        - "CI_COMMIT_SHA"
      deny:
        - "AWS_SECRET_ACCESS_KEY"
        - "DATABASE_PASSWORD"

これにより、不要な機密シークレットがサブエージェントに公開されないようにします。

並列エージェント実行​

並列実行の設定​

並列実行により複数のサブエージェントを同時に実行でき、タスク完了時間を大幅に短縮できます。

// settings.json で
{
  "cursor.subagents.execution": {
    "strategy": "parallel",
    "maxConcurrent": 4,
    "staggerDelay": 1000
  }
}
  • maxConcurrent: 同時に実行されるサブエージェントの最大数
  • staggerDelay: 各サブエージェントの開始間で待機するミリ秒数（リソーススパイクを防止）

並列実行の例​

# .cursor/subagents/parallel-config.yaml
planner:
  model: cursor-pro
  description: "Refactor the authentication system across frontend and backend"

execution:
  strategy: parallel

subagents:
  - name: "frontend-auth"
    model: cursor-max
    description: "Refactor React authentication components to use new auth context"
    scope:
      files:
        include: ["src/components/auth/**", "src/contexts/AuthContext.tsx"]
      strictMode: true
    tools: ["read", "write", "edit"]

  - name: "backend-auth"
    model: cursor-max
    description: "Refactor backend authentication middleware and JWT handling"
    scope:
      files:
        include: ["src/api/middleware/auth.ts", "src/utils/jwt.ts"]
      strictMode: true
    tools: ["read", "write", "edit"]

  - name: "auth-tests"
    model: cursor-fast
    description: "Update authentication tests for the new structure"
    scope:
      files:
        include: ["test/auth/**"]
      strictMode: true
    tools: ["read", "write", "terminal"]

  - name: "auth-docs"
    model: cursor-fast
    description: "Update authentication documentation"
    scope:
      files:
        include: ["docs/auth/**", "README.md"]
      strictMode: true
    tools: ["read", "write"]

この設定では、4 つのサブエージェントすべてが（1 秒のずれで）同時に開始され、それぞれの領域で並列に作業します。

並列実行結果の処理​

プランナーはすべての並列サブエージェントから結果を収集し、総合します：

// プランナー総合設定
{
  "cursor.subagents.planner": {
    "synthesisStrategy": "merge",
    "conflictResolution": "planner-decides",
    "generateSummary": true,
    "summaryFormat": "markdown"
  }
}
ヒント

並列サブエージェントが競合する変更を生成した場合、プランナーはあるアプローチを別のアプローチより優先することで解決できます。generateSummary を有効にして、プランナーがコンフリクト解決の決定を人間が読める形式で説明するようにします。変更を受け入れる前にこのサマリーをレビューしてください。

サブエージェントオーケストレーション​

オーケストレーション戦略​

プランナーは異なる戦略でサブエージェントをオーケストレーションできます：

戦略 1: ファンアウト / ファンイン

プランナーがタスクを分解し、サブタスクを並列サブエージェントに割り当て、すべての結果を収集し、総合します。

execution:
  strategy: parallel
  synthesis:
    type: "merge"
    order: "completion"  # 完了時に結果を収集

戦略 2: パイプライン

サブエージェントが順次実行され、各々が前の出力を消費します。

execution:
  strategy: sequential
  pipeline:
    - agent: "schema-generator"
      output: "schema_result"
    - agent: "api-builder"
      input: "schema_result"
      output: "api_result"
    - agent: "test-writer"
      input: "api_result"
      output: "test_result"

戦略 3: アダプティブ

プランナーがタスクの依存関係に基づいて、サブエージェントを並列または順次で実行するか動的に決定します。

execution:
  strategy: adaptive
  rules:
    - condition: "no_dependencies"
      action: "parallel"
    - condition: "has_dependencies"
      action: "sequential"
    - condition: "partial_dependencies"
      action: "mixed"

動的サブエージェント作成​

プランナーはタスク実行中に発見した内容に基づいてサブエージェントを動的に作成できます：

// settings.json で
{
  "cursor.subagents.dynamicCreation": true,
  "cursor.subagents.dynamicMaxAgents": 8,
  "cursor.subagents.dynamicTemplate": {
    "model": "cursor-fast",
    "tools": ["read", "write", "edit"],
    "scope": {
      "strictMode": true
    }
  }
}

動的作成を有効にすると、プランナーは必要に応じて新しいサブエージェントをスポーンできます。例えば、プランナーがタスクに Python と TypeScript の両方のファイルが含まれることを発見した場合、Python 専用サブエージェントと TypeScript 専用サブエージェントを実行時に作成できます。

警告

動的サブエージェント作成は、プランナーが並列性の必要性を過大評価した場合、ランナウェイエージェントスポーンを引き起こす可能性があります。常に dynamicMaxAgents を妥当な制限（4-8）に設定し、トークン総使用量を監視してください。プランナーが多すぎるサブエージェントを作成すると、タスク完了前にトークン予算を使い果たす可能性があります。

チェックポイントを使ったオーケストレーション​

サブエージェント実行間にチェックポイントを追加して、人的レビューや自動検証を可能にします：

execution:
  strategy: sequential
  checkpoints:
    - after: "schema-generator"
      action: "validate"
      validator: "npm run typecheck"
      onFail: "retry"
      maxRetries: 2

    - after: "api-builder"
      action: "review"
      reviewer: "human"
      timeout: 300000
      onTimeout: "proceed"
ヒント

チェックポイントは、続行する前に中間結果を検証したい CI/CD 統合で特に価値があります。validate チェックポイントはコマンドを実行し、正常に終了した場合のみ続行し、review チェックポイントは人的入力のために一時停止します。

監視とデバッグ​

サブエージェントステータスの表示​

Cursor サイドバーからすべての実行中サブエージェントを監視します：

# コマンドパレット：Cursor: Show Subagent Dashboard

ダッシュボードには以下が表示されます：

Subagent Dashboard
==================
Planner: [running] cursor-pro
  Task: "Refactor authentication system"
  Steps: 3/5

Subagents:
  [completed] frontend-auth (cursor-max)
    Files changed: 4
    Tokens used: 12,400

  [running] backend-auth (cursor-max)
    Current file: src/api/middleware/auth.ts
    Tokens used: 8,200

  [running] auth-tests (cursor-fast)
    Current file: test/auth/login.test.ts
    Tokens used: 3,100

  [queued] auth-docs (cursor-fast)
    Waiting for: backend-auth to complete

Total tokens: 23,700 / 100,000

スコープ違反のデバッグ​

サブエージェントがスコープ外のファイルにアクセスを試みた場合、その試行はログに記録されます：

# スコープ違反ログを表示
# コマンドパレット：Cursor: Show Subagent Logs
[WARN] Subagent "frontend-auth" attempted to read src/api/routes.ts
       Access denied: file is outside the agent's scope
       Scope includes: src/components/auth/**, src/contexts/AuthContext.tsx

[WARN] Subagent "backend-auth" attempted to run terminal command: npm install
       Command blocked: not in allowedCommands list
       Allowed commands: npm test, npx tsc, git status
ヒント

同じサブエージェントから繰り返しスコープ違反が見られる場合、スコープが厳しすぎる可能性があります。タスクをレビューし、アクセスを試み続けているファイルを含めるようにスコープを拡大することを検討してください。必要なファイルにアクセスできないフラストレートしたサブエージェントは、失敗した試行でトークンを無駄にします。

ベストプラクティス​

  • プランナーに cursor-pro 以上を使用し、シンプルなサブエージェントにはより安価なモデルを使用
  • ファイルスコープに常に strictMode: true を設定して不要なアクセスを防止
  • ターミナルアクセスを持つサブエージェントには allowedCommands を設定
  • 並列サブエージェント間で書き込みスコープが重複しないことを確認
  • リソース使用を制御するために maxConcurrent 制限を設定
  • 検証が必要な重要タスクにチェックポイントを使用
  • 予算枯渇を避けるためすべてのサブエージェントのトークン使用量を監視
  • スコープが正しいことを確認してから並列に移行し、最初は順次実行を使用
  • 並列結果を受け入れる前にプランナーの総合サマリーをレビュー
  • チーム一貫性のためにサブエージェント設定をバージョン管理
警告

サブエージェントはデフォルトでプランナーのシステムプロンプトを継承します。システムプロンプトに機密情報が含まれている場合、不要なコンテキストを除外するサブエージェント固有のプロンプトの使用を検討してください。cursor.subagents.inheritPlannerPrompt 設定を false に設定して構成してください。

結論​

Cursor のサブエージェントは、複雑なタスクを管理しやすく専門化されたユニットに分解する強力な方法を提供します。モデルを慎重に選択し、厳格なファイルスコープを設定し、セキュリティ境界をセットアップし、適切なオーケストレーション戦略を選択することで、効率的かつ安全なマルチエージェントワークフローを構築できます。

最も重要な考慮事項は：タスクの複雑さにモデルを一致させ、ファイルアクセスの問題を防ぐために厳格なスコープ適用を使用し、並列に移行する前に順次実行から始めることです。これらのプラクティスにより、サブエージェントは単一のエージェントでは圧倒されるような大規模開発タスクを処理するための信頼できるツールとなります。