하위 에이전트

하위 에이전트는 Cursor의 에이전트가 작업을 위임할 수 있는 특화된 AI 도우미입니다. 각 하위 에이전트는 자체 컨텍스트 창에서 작동하며, 특정 유형의 작업을 처리한 후 결과를 상위 에이전트에 반환합니다. 하위 에이전트를 사용해 복잡한 작업을 나누고, 병렬로 처리하며, 메인 대화의 컨텍스트를 유지할 수 있습니다.

에디터, CLI 및 클라우드 에이전트에서 하위 에이전트를 사용할 수 있습니다.

하위 에이전트 작동 방식

Agent는 복잡한 작업을 만나면 자동으로 하위 에이전트를 실행할 수 있습니다. 하위 에이전트는 필요한 모든 컨텍스트가 담긴 프롬프트를 받아 자율적으로 작업하고, 결과를 담은 최종 메시지를 반환합니다.

하위 에이전트는 비어 있는 컨텍스트에서 시작합니다. 이전 대화 기록에 접근할 수 없으므로, 상위 에이전트가 관련 정보를 프롬프트에 포함합니다.

포그라운드 vs 백그라운드

하위 에이전트는 두 가지 모드 중 하나로 실행됩니다.

기본 제공 하위 에이전트

Cursor에는 컨텍스트를 많이 사용하는 작업을 자동으로 처리하는 기본 제공 하위 에이전트가 세 개 있습니다. 이 하위 에이전트는 컨텍스트 창 한도에 도달한 에이전트 대화를 분석해 설계되었습니다.

이러한 하위 에이전트가 필요한 이유

이 세 작업에는 공통된 특징이 있습니다. 중간 출력이 많고, 특화된 프롬프트와 도구를 활용하면 효과적이며, 상당한 컨텍스트를 소비할 수 있습니다. 이를 하위 에이전트로 실행하면 여러 문제를 해결할 수 있습니다.

• 컨텍스트 격리 — 중간 출력은 하위 에이전트에 남습니다. 상위 에이전트는 최종 요약만 확인합니다.
• 모델 유연성 — Explore 하위 에이전트는 기본적으로 더 빠른 모델을 사용합니다. 따라서 메인 에이전트로 검색 한 번을 실행하는 시간에 병렬 검색 10회를 실행할 수 있습니다.
• 특화된 구성 — 각 하위 에이전트에는 특정 작업에 맞게 조정된 프롬프트와 도구 접근 권한이 있습니다.
• 비용 효율성 — 더 빠른 모델은 비용이 적게 듭니다. 토큰을 많이 사용하는 작업을 적절한 모델을 사용하는 하위 에이전트로 격리하면 전체 비용을 줄일 수 있습니다.

이러한 하위 에이전트를 설정할 필요는 없습니다. Agent가 적절한 경우 자동으로 사용합니다.

서브에이전트를 사용해야 할 때

빠른 시작

Agent는 필요에 따라 자동으로 서브에이전트를 사용합니다. Agent에 요청해 사용자 정의 서브에이전트를 만들 수도 있습니다.

더 세밀하게 제어하려면 프로젝트 또는 사용자 디렉터리에서 사용자 정의 서브에이전트를 직접 만드세요.

사용자 정의 서브에이전트

사용자 정의 서브에이전트를 정의하여 전문 지식을 담고, 팀 표준을 적용하며, 반복적인 워크플로를 자동화하세요.

파일 위치

이름이 충돌하는 경우 프로젝트 하위 에이전트가 우선합니다. 여러 위치에 동일한 이름의 하위 에이전트가 있으면 .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 필드는 하위 에이전트가 사용할 모델을 지정합니다. 두 가지 옵션이 있습니다.

하위 에이전트에 상위 에이전트와 동일한 추론 능력이 필요한 경우 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.

하위 에이전트 사용하기

자동 위임

Agent는 다음을 기준으로 작업을 선제적으로 위임합니다.

• 작업의 복잡성과 범위
• 프로젝트에 정의된 사용자 지정 하위 에이전트 설명
• 현재 컨텍스트와 사용 가능한 도구

설명 필드에 "use proactively" 또는 "always use for" 같은 문구를 포함하면 자동 위임을 유도할 수 있습니다.

명시적 호출

프롬프트에서 /name 구문을 사용해 특정 하위 에이전트를 요청합니다:

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

자연스럽게 언급하여 하위 에이전트를 호출할 수도 있습니다:

> 검증기 서브에이전트로 인증 흐름이 완료되었는지 확인하세요> > 디버거 서브에이전트에게 이 오류를 조사하게 하세요> > 결제 모듈에서 보안 감사 서브에이전트를 실행하세요

병렬 실행

처리량을 극대화하려면 여러 하위 에이전트를 동시에 실행하세요:

> API 변경 사항을 검토하고 문서도 동시에 업데이트하세요

Agent가 하나의 메시지에서 여러 Task 도구를 호출하므로 하위 에이전트가 동시에 실행됩니다.

클라우드 하위 에이전트

로컬 에이전트 세션에서 자체 VM과 브랜치에서 실행되는 클라우드 하위 에이전트에 작업을 위임할 수 있습니다. 장시간 실행되거나 병렬로 진행되는 작업은 클라우드에서 처리되므로 로컬 작업 공간을 깔끔하고 원활하게 유지할 수 있습니다. 상위 에이전트는 중단 없이 로컬 또는 클라우드에서 계속 실행됩니다. 클라우드 하위 에이전트는 Cursor 데스크톱 앱의 에이전트 창에서 실행됩니다.

/in-cloud로 클라우드 하위 에이전트 시작하기

/in-cloud를 입력하면 다음에 제출하는 작업이 클라우드 하위 에이전트로 실행됩니다. 작업을 수행할 자체 VM과 브랜치가 생성됩니다.

CI 수정, 이슈 조사, 로컬에서 계속 작업하면서 코드베이스 탐색 등 장시간 실행되거나 병렬로 수행되는 작업을 분리하는 데 유용합니다.

/babysit으로 PR 관리하기

/babysit 또는 빠른 작업 버튼을 클릭해 클라우드 하위 에이전트에게 풀 리퀘스트 관리를 맡기세요. 클라우드 에이전트는 로컬 세션을 점유하지 않고 원격에서 반복적으로 작업하여 PR을 머지할 수 있도록 준비합니다.

클라우드 하위 에이전트는 리포지토리에 구성된 환경을 사용하며, 다른 클라우드 에이전트와 동일한 모델 및 기능 규칙을 따릅니다. 클라우드 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: Test automation expert. Use proactively to run tests and fix failures.---You are a test automation expert.When you see code changes, proactively run appropriate tests.If tests fail:1. Analyze the failure output2. Identify the root cause3. Fix the issue while preserving test intent4. Re-run to verifyReport test results with:- Number of tests passed/failed- Summary of any failures- Changes made to fix issues

모범 사례

• 역할이 명확한 서브에이전트 작성 — 각 서브에이전트는 하나의 명확한 책임만 맡아야 합니다. 범용 "도우미" 에이전트는 피하세요.
• 설명 작성에 공들이기 — description 필드는 Agent가 서브에이전트에 작업을 위임할 시점을 결정합니다. 다듬는 데 시간을 투자하세요. 프롬프트를 작성해 적절한 서브에이전트가 호출되는지 확인하며 테스트하세요.
• 프롬프트를 간결하게 유지 — 길고 장황한 프롬프트는 집중도를 떨어뜨립니다. 구체적이고 직접적으로 작성하세요.
• 서브에이전트를 버전 관리에 추가 — 팀 전체가 활용할 수 있도록 .cursor/agents/를 리포지토리에 커밋하세요.
• Agent가 생성한 에이전트로 시작 — Agent가 초기 구성을 초안으로 만들도록 한 다음 사용자 지정하세요.
• 파일 출력에 훅 사용 — 서브에이전트가 구조화된 출력 파일을 생성해야 한다면, 훅을 사용해 결과를 일관되게 처리하고 저장하는 것을 고려하세요.

피해야 할 안티패턴

• 모호한 설명 — "일반 작업에 사용"이라고만 하면 언제 위임해야 하는지 Agent가 알 수 없습니다. 구체적으로 작성하세요. 예: "OAuth 제공업체를 사용하는 인증 흐름을 구현할 때 사용."
• 지나치게 긴 프롬프트 — 2,000단어짜리 프롬프트가 하위 에이전트를 더 똑똑하게 만들지는 않습니다. 오히려 더 느려지고 유지 관리도 어려워집니다.
• 슬래시 명령어 중복 — 작업이 단일 목적이고 컨텍스트 격리가 필요하지 않다면 스킬이나 명령어를 사용하세요.
• 너무 많은 하위 에이전트 — 집중된 하위 에이전트 2~3개로 시작하세요. 명확하고 서로 구분되는 사용 사례가 있을 때만 추가하세요.

하위 에이전트 관리

하위 에이전트 생성

하위 에이전트를 만드는 가장 쉬운 방법은 Agent에게 생성해 달라고 요청하는 것입니다:

.cursor/agents/(프로젝트) 또는 ~/.cursor/agents/(사용자)에 마크다운 파일을 추가하여 하위 에이전트를 직접 만들 수도 있습니다.

서브에이전트 보기

Agent는 사용 가능한 도구로 모든 사용자 정의 서브에이전트를 제공합니다. 프로젝트의 .cursor/agents/ 디렉터리를 확인하면 구성된 서브에이전트를 확인할 수 있습니다.

성능 및 비용

하위 에이전트에는 장단점이 있습니다. 이를 이해하면 언제 사용할지 판단하는 데 도움이 됩니다.

토큰 및 비용 고려 사항

• 하위 에이전트는 각각 토큰을 소비합니다 — 각 하위 에이전트는 자체 컨텍스트 창과 토큰 사용량을 가집니다. 하위 에이전트 5개를 병렬로 실행하면 단일 에이전트보다 약 5배 많은 토큰을 사용합니다.
• 오버헤드를 고려하세요 — 빠르고 단순한 작업에서는 메인 에이전트가 더 빠른 경우가 많습니다. 하위 에이전트는 복잡하거나 장시간 실행되는 작업, 병렬 작업에서 강점을 발휘합니다.
• 하위 에이전트가 더 느릴 수 있습니다 — 장점은 속도가 아니라 컨텍스트 격리입니다. 단순한 작업을 수행하는 하위 에이전트는 새 컨텍스트에서 시작하므로 메인 에이전트보다 느릴 수 있습니다.

FAQ