본문으로 건너뛰기

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"]
경고

두 서브에이전트가 동시에 동일한 파일에 쓰면 플래너가 자동으로 해결할 수 없는 병합 충돌이 발생합니다. 쓰기 가능한 서브에이전트 간에 파일 스코프가 겹치지 않는지 항상 확인하세요. 실행 전에 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의 서브에이전트는 복잡한 작업을 관리 가능하고 전문화된 단위로 분해하는 강력한 방법을 제공합니다. 모델을 신중하게 선택하고, 엄격한 파일 스코프를 설정하고, 보안 경계를 설정하고, 올바른 오케스트레이션 전략을 선택함으로써 효율적이고 안전한 멀티 에이전트 워크플로우를 구축할 수 있습니다.

가장 중요한 고려 사항은: 작업 복잡도에 모델을 매칭하고, 파일 접근 문제를 방지하기 위해 엄격한 스코프 적용을 사용하며, 병렬로 전환하기 전에 순차적 실행으로 시작하는 것입니다. 이러한 관행으로 서브에이전트는 단일 에이전트에게는 압도적일 대규모 개발 작업을 처리하는 신뢰할 수 있는 도구가 됩니다.