Cursor 커스텀 서브에이전트 — 어디에 정의하나?

Cursor 커스텀 서브에이전트는 마크다운 + YAML 프론트매터로 “언제 무엇을 할지”를 고정한 전문 자식 Agent입니다. 부모 Agent가 위임하면 자체 컨텍스트 창에서 일하고, 최종 메시지만 부모에게 돌려줍니다. 중간 탐색·셸·검증이 메인 대화를 잠식하지 않게 하는 장치가 핵심입니다.

이 글의 축은 셋입니다. 파일 위치는? · 언제 위임하나? · 부모 프롬프트에 뭘 남기나? 요금·플랜·토큰 한도·제휴·창작 후기는 없습니다.

근거는 Cursor 공식 Subagents입니다. 동작·파일 위치·위임·프론트매터만 다룹니다.

파일 위치는?

한 줄 답: 프로젝트 전용은 .cursor/agents/, 모든 프로젝트 공용은 ~/.cursor/agents/ 에 .md 파일을 둡니다. 이름이 겹치면 프로젝트 정의가 이기고, 같은 프로젝트 안에서는 .cursor/가 .claude/·.codex/보다 우선합니다.

유형	경로	범위
프로젝트	`.cursor/agents/`	현재 레포만
프로젝트(호환)	`.claude/agents/`, `.codex/agents/`	현재 레포만
사용자	`~/.cursor/agents/`	현재 사용자 전 프로젝트
사용자(호환)	`~/.claude/agents/`, `~/.codex/agents/`	현재 사용자 전 프로젝트

각 파일은 YAML 프론트매터 + 본문 프롬프트입니다. 문서상 주요 필드는 다음과 같습니다.

필드	기본	역할
`name`	파일명	표시명·식별자(소문자·하이픈)
`description`	—	Task 힌트. Agent가 위임 여부를 읽을 신호
`model`	`inherit`	부모와 동일, 또는 특정 모델 ID
`readonly`	`false`	`true`면 쓰기·상태 변경 셸 제한
`is_background`	`false`	`true`면 부모를 막지 않고 백그라운드 실행

최소 예(검증 전용):

---
name: verifier
description: Validates completed work. Use after tasks are marked done.
model: inherit
readonly: true
---

You are a skeptical validator. Verify claimed work actually works.
Run relevant checks. Report passed vs incomplete. Do not accept claims at face value.

실무 배치:

팀 공통 역할(verifier·debugger)은 .cursor/agents/에 커밋합니다.
개인 습관만 쓰는 에이전트는 ~/.cursor/agents/ 에 둡니다.
이름 충돌이 나면 프로젝트 쪽이 이깁니다. 의도치 않은 덮어쓰기를 피하려면 역할별 고유 name 을 씁니다.
Claude/Codex 호환 폴더도 읽히지만, Cursor 중심이면 .cursor/agents/를 단일 소스로 두는 편이 안전합니다.

repo/
  .cursor/
    agents/
      verifier.md      ← project, shared via VCS
      debugger.md
~/.cursor/
  agents/
    my-notes-helper.md ← user-wide only

문서 권장: 초안은 Agent에게 “.cursor/agents/….md 만들어 줘”로 받고, description을 실사용 프롬프트로 다듬습니다. 모호한 “helps with coding”은 위임 신호가 되지 않습니다.

언제 위임하나?

한 줄 답: 긴 탐색·병렬 작업·다단계 전문 검증처럼 컨텍스트 격리가 필요할 때 위임하고, 한 방이면 끝나는 단순 작업은 스킬·명령·부모에 남깁니다.

문서의 “when to use subagents vs skills” 축을 정리하면 다음과 같습니다.

서브에이전트에 맡김	부모·스킬에 남김
긴 리서치·코드베이스 탐색(중간 출력이 noisy)	체인지로그 한 줄·import 정렬 같은 단발
여러 워크스트림을 병렬로	빠른 반복 액션 한 번
다단계 전문 지식(보안 감사·디버그)	별도 컨텍스트 창이 필요 없음
독립 검증(주장 vs 실제)	부모가 이미 맥락을 다 가진 짧은 수정

빌트인 서브에이전트(explore·bash·browser)는 중간 출력이 커서 메인 컨텍스트를 잠식하기 쉬워 자동으로 쓰이도록 설계되어 있습니다. 커스텀은 그 위에 팀 기준·역할을 고정할 때 둡니다.

위임 트리거 실무:

자동: description에 “use proactively”, “always use for …”처럼 언제 쓸지를 분명히 적습니다.
명시: 채팅에서 /verifier …, /debugger … 또는 “verifier 서브에이전트로 …”라고 부릅니다.
병렬: 한 메시지에 “API 리뷰와 문서 업데이트를 병렬로”처럼 쓰면 Agent가 여러 Task를 동시에 낼 수 있습니다.
포그라운드 vs 백그라운드: 결과가 즉시 필요하면 기본(포그라운드), 긴 조사는 is_background: true 또는 긴 작업으로 백그라운드에 둡니다.

Delegate when:
- Intermediate output is noisy (search, logs, browser DOM)
- You need a second opinion (verifier) with a fresh context
- Two+ independent streams can run at once

Do NOT spin a custom subagent for:
- One-shot format / rename / changelog
- Vague “helper” roles without a triggering description
- Duplicating a skill that does not need isolation

안티패턴(문서): 수십 개의 모호한 헬퍼, 2,000단어 장문 프롬프트, 스킬로 충분한 단발을 서브에이전트로 복제. 2~3개의 초점 역할부터 시작합니다.

부모 프롬프트에 뭘 남기나?

한 줄 답: 서브에이전트는 이전 대화 이력을 보지 않으므로, 부모가 넘기는 프롬프트에 목표·범위·성공 기준·필요 경로를 넣고, 부모 쪽에는 오케스트레이션·최종 병합·사용자와의 다음 결정을 남깁니다.

문서 핵심: “Subagents start with a clean context. The parent agent includes relevant information in the prompt.”

자식(서브에이전트)에 넣을 것	부모에 남길 것
Done when / Out of scope	전체 티켓 목표·우선순위
관련 파일 경로·재현 절차·에러 로그 요약	여러 자식 결과의 병합·충돌 해결
역할 프롬프트에 이미 있는 체크리스트는 짧게 참조	사용자 확인이 필요한 선택지
산출 형식(통과/실패 목록, 심각도)	다음 위임 여부·재개(agent ID)

부모 프롬프트(세션)에 고정해 두면 좋은 한 줄들:

Parent keeps:
- Overall goal and acceptance for the user-facing change
- Which specialist to call (/verifier, /debugger) and in what order
- Merge policy: parent integrates diffs; subagents report only
- Do not assume subagents see prior chat — pass paths and criteria each time

Parent hands off in the Task prompt:
- Goal (one sentence)
- Touch / Do-not-touch paths
- Success checks (commands or observable outcomes)
- Return format (passed / failed / open questions)

오케스트레이터 패턴(문서 예시): Planner → Implementer → Verifier. 각 핸드오프에 구조화된 산출을 넣어 다음 자식이 추측하지 않게 합니다. 검증은 readonly: true로 두면 쓰기 권한이 제한되어 “고치면서 검증”이 섞이기 어렵습니다.

부모가 남기지 말아야 할 것:

자식이 이미 .md 본문에 가진 장황한 역할 설명 전체 복붙
“알아서 레포 전체를 살펴봐”처럼 범위 없는 위임
시크릿·배포 승인·머지 버튼처럼 사람/부모가 쥐어야 하는 권한

# Bad handoff
"Fix auth somehow."

# Better handoff (parent → verifier)
"Claimed done: OAuth callback in apps/web/src/auth/callback.ts.
Verify end-to-end: login → callback → session cookie.
Out of scope: redesign UI, touch apps/admin.
Return: passed checks, failed checks, incomplete items."

자주 묻는 질문

프로젝트와 사용자 정의가 같은 이름이면?
프로젝트 서브에이전트가 우선합니다. 같은 프로젝트에서 경로가 여러 개면 .cursor/가 .claude/·.codex/보다 앞선다고 문서에 명시되어 있습니다.

description만 잘 쓰면 자동 위임되나?
Agent는 작업 복잡도·description·현재 컨텍스트를 보고 위임합니다. “use proactively / always use for” 문구가 자동 위임을 돕습니다. 그래도 중요한 검증은 /name으로 명시하는 편이 안전합니다.

서브에이전트가 또 서브에이전트를 띄울 수 있나?
가능하지만 중첩 한도가 있습니다. 문서상 메인과 직계 자식은 띄울 수 있고, 그 아래는 더 깊이 띄우지 못합니다. 훅·도구 정책·모드가 Task를 막을 수 있습니다. 복잡한 파이프는 부모가 전문가를 직렬/병렬로 조정하는 편이 단순합니다.

간단한 작업에도 커스텀을 만들어야 하나?
아니요. 단발·격리 불필요면 스킬·명령을 쓰고, 커스텀은 반복되는 전문 역할에만 둡니다.

무엇을 기억하면 되나?

정의는 .cursor/agents/(또는 ~/.cursor/agents/)의 md, 위임은 격리·병렬·전문 검증이 필요할 때, 부모는 목표·순서·병합을 쥐고 자식 프롬프트에 컨텍스트를 매번 실어 보냅니다. 근거: Cursor Subagents. 요금·제휴 없음.

공식 문서는 어디인가?

Cursor — Subagents — 위치, 프론트매터, 자동/명시 위임, 포그라운드·백그라운드, 베스트 프랙티스
인접: subagent-brief (위임 브리프 한 장), cursor-skills-vs-rules (스킬 vs 규칙), agent-context-budget (같은 세션 요약)