서브에이전트에 일을 넘길 때 브리프는?
Cursor 서브에이전트는 부모 Agent가 맡긴 일을 자체 컨텍스트 창에서 처리한 뒤, 결과를 부모에게 돌려줍니다. 탐색·셸·브라우저처럼 중간 출력이 noisy한 작업이나, 검증·디버그처럼 전문화가 필요한 일을 분리할 때 씁니다. 근거는 Subagents입니다.
이 글은 위임 브리프만 다룹니다. 성공 기준은 무엇인가 · 컨텍스트에 무엇을 넣을까 · 결과를 어떻게 받나. AI 에이전트 컨텍스트 예산 글(긴 세션 progress 요약)과 축이 다릅니다. 그 글은 같은 대화·다음 세션을 이어 가는 최소 상태이고, 여기는 자식에게 넘기는 한 장의 위임서입니다. 요금·토큰·창 크기 숫자는 다루지 않습니다.
성공 기준은?
한 줄 답: 서브에이전트가 무엇을 검증·산출하면 “끝”인지를 한두 문장으로 적고, 범위 밖(하지 말 것) 을 같이 적습니다. “알아서 좋게”는 성공 기준이 아닙니다.
문서상 서브에이전트는 프롬프트를 받고 자율적으로 일한 뒤 최종 메시지로 결과를 반환합니다. 부모 대화 이력을 보지 않으므로, 성공 정의가 브리프에 없으면 자식은 추측으로 범위를 넓히거나 조기에 끝냅니다.
성공 기준 체크리스트:
| 항목 | 넣을 것 | 넣지 말 것 |
|---|---|---|
| Done when | 검증 가능한 산출(파일 경로, 테스트 통과, 보고서 항목) | “품질 좋게”, “대충 봐줘” |
| Out of scope | 건드리지 말 경로·머지·배포·시크릿 | 열린 아이디어 나열만 |
| Evidence | 부모가 확인할 증거 형식(로그 요약, 실패 목록) | 전체 덤프를 본문에 복붙하라고만 |
| Mode 힌트 | 순차면 foreground, 긴 독립이면 background | 요금·모델 가격 언급 |
실무 예시(검증 위임):
## Goal
auth 플로우가 “완료”로 표시된 범위가 실제로 동작하는지 검증한다.
## Done when
- 관련 테스트 또는 최소 수동 확인 단계를 실행했다
- 통과/실패/미완을 항목별로 보고한다
- 주장만 있고 재현·테스트가 없으면 “incomplete”로 표시한다
## Out of scope
- 새 기능 구현, 대규모 리팩터, 시크릿·프로덕션 자격 증명 접근문서의 verifier 패턴이 이 축입니다. “완료라고 적혀 있다”를 믿지 말고, 구현·테스트를 확인한 뒤 통과 vs 미완을 보고하게 합니다. description에 “Use after tasks are marked done…”처럼 언제 부를지를 쓰면 자동 위임 신호도 커집니다.
오케스트레이션 힌트: Planner → Implementer → Verifier처럼 핸드오프마다 구조화된 산출을 다음 브리프에 넣습니다. 중첩 위임은 제품이 허용하는 깊이(문서: 메인과 직계 서브까지 자식을 띄울 수 있고, 그 아래는 추가 스폰 제한)를 가정하고, 가능하면 부모가 전문가에게 평평하게 위임하는 편이 디버깅이 쉽습니다.
컨텍스트는 뭘 넣나?
한 줄 답: 서브에이전트는 빈 컨텍스트로 시작합니다. 부모 채팅 이력·이전 결정·열린 파일 목록을 가정하지 말고, 이번 위임에 필요한 최소 팩트만 프롬프트(또는 커스텀 에이전트 본문)에 넣습니다.
Subagents 문서: Subagents start with a clean context. The parent agent includes relevant information in the prompt since subagents don’t have access to prior conversation history.
넣을 것 / 빼 둘 것:
| 넣을 것 | 이유 | 빼 둘 것 |
|---|---|---|
| 목표·성공 기준(위 절) | 자식이 끝점을 안다 | 긴 대화 전문 |
| 핵심 경로·심볼·티켓 ID | 탐색 범위 축소 | 관련 없는 레포 맵 전체 |
| 이미 확정된 결정 1–3줄 | 되돌리기 비싼 선택 고정 | 실험 로그·실패한 가설 전부 |
| 제약(readonly, 금지 경로, 브랜치) | 안전·충돌 방지 | 시크릿·토큰 본문 |
| 산출물 형식(경로, 섹션 헤더) | 부모가 파싱·병합하기 쉬움 | “창의적으로 알아서” |
커스텀 서브에이전트(.cursor/agents/*.md)를 쓸 때는 frontmatter의 description 이 라우팅 신호입니다. 막연한 “helps with coding”보다 “OAuth 인증 구현 시 사용 / 완료 후 검증에 사용”처럼 구체적으로 씁니다. 본문 프롬프트는 짧고 단일 책임. 문서 anti-pattern: 2,000단어 장문, 수십 개의 모호한 헬퍼.
빌트인 Explore / Bash / Browser는 중간 출력이 커서 자동으로 격리됩니다. 사람이 브리프를 쓸 때도 같은 원칙입니다. 중간 노이즈는 자식 창에 두고, 부모에게는 요약·경로·결정만 돌아오게 합니다.
병렬로 여러 자식을 띄울 때는 기본이 같은 checkout 공유입니다. 동시에 파일을 고치면 덮어쓸 수 있으니, 문서대로 격리(워크트리·자체 환경) 를 요청할지 브리프에 명시합니다. git worktree 에이전트 글은 격리 축, 이 글은 한 번의 위임 문장 축입니다.
context-budget과의 경계 한 줄: progress 파일은 세션·티켓을 이어 가는 상태이고, 서브에이전트 브리프는 그 상태에서 이번 자식에게 맡길 한 조각입니다. progress 전체를 붙여 넣지 말고, Goal / Paths / Blocked에서 이번 조각에 필요한 줄만 복사합니다.
결과를 어떻게 받나?
한 줄 답: 부모는 서브에이전트의 최종 메시지를 받습니다. 순차 의존이면 foreground(끝날 때까지 대기), 긴 독립·병렬이면 background(즉시 반환 후 진행). 이어가려면 에이전트 ID로 resume 합니다.
모드:
| 모드 | 동작 | 언제 |
|---|---|---|
| Foreground | 완료까지 블록, 결과를 바로 반환 | 다음 단계가 이 출력에 의존 |
| Background | 즉시 반환, 독립 실행 | 긴 작업·병렬 스트림 |
결과 수신 실무:
- 브리프에 “최종 답변 형식”을 고정한다. 예:
## Summary/## Paths/## Passed/## Failed/## Open. 부모가 다음 턴에 그대로 인용·머지하기 쉽습니다. - Background 진행 확인. 문서는 background 출력을
~/.cursor/subagents/에 쓴다고 안내합니다. 부모(또는 사람)가 파일을 읽어 진행을 점검할 수 있습니다. - Resume. 실행마다 에이전트 ID가 돌아옵니다. “Resume agent <id> and …”로 이전 컨텍스트를 유지한 채 이어서 묻습니다. 긴 조사·실패 재분석을 새 브리프로 처음부터 다시 쓰지 않아도 됩니다.
- 실패 시. 서브에이전트는 부모에게 오류 상태를 반환합니다. 부모는 재시도, 컨텍스트 추가 후 resume, 또는 다른 전문가에게 재위임합니다.
- 훅·파일 산출. 구조화 파일을 항상 남기려면 문서 best practice대로 hooks로 결과 저장을 맞출 수 있습니다. 브리프에는 “레포에
reports/<slug>.md를 쓰고 최종 메시지에는 경로만”처럼 적습니다.
명시 호출: /verifier …, /debugger … 또는 “Use the verifier subagent to …”. 병렬은 한 메시지에서 여러 작업을 요청하면 Agent가 여러 Task를 동시에 띄울 수 있습니다. 클라우드 위임(/in-cloud, /autopilot)은 로컬 세션을 비우며 VM·브랜치에서 돌리는 축이므로, 로컬 서브에이전트 브리프와 섞어 쓰지 말고 목표(격리·장기)를 분명히 합니다.
FAQ
서브에이전트 브리프와 context-budget 요약의 차이는?
context-budget은 긴 세션에서 Goal / Done / Next / Blocked 같은 progress를 레포에 남겨 같은 작업 줄을 잇는 글입니다. 이 글은 그 줄에서 자식 컨텍스트로 넘기는 위임 패킷(성공 기준·최소 팩트·반환 형식)입니다.
Skills·slash commands와 언제 갈라지나요?
문서 기준: 컨텍스트 격리·다단계·병렬·독립 검증이면 서브에이전트, 한 방의 반복 작업(changelog, format)이면 skill/command가 맞습니다. 단순 작업을 위해 서브에이전트를 새로 만들지 않습니다.
커스텀 에이전트 파일은 어디에 두나요?
프로젝트는 .cursor/agents/(호환: .claude/agents/, .codex/agents/), 유저 전역은 ~/.cursor/agents/ 등. 이름 충돌 시 프로젝트·.cursor/ 우선. 팀은 레포에 커밋합니다.
자식이 또 자식을 띄우나요?
문서상 중첩은 제한적으로 가능합니다(메인과 직계 서브까지). 정책·훅·모드에 따라 Task 스폰이 막힐 수 있습니다. 복잡한 파이프는 부모가 평평하게 전문가에게 위임하는 구성을 기본으로 둡니다.
출처 (Sources)
- Subagents — 격리 컨텍스트, foreground/background, 빌트인·커스텀, resume, best practices