코딩 에이전트의 작동 방식부터 계획 수립, 컨텍스트 관리, 규칙·스킬 확장, 병렬 실행과 디버그 모드까지 Cursor 에이전트를 효과적으로 활용하는 방법을 정리한 가이드.
URL: https://cursor.com/blog/agent-best-practices
코딩 에이전트는 소프트웨어가 만들어지는 방식을 바꾸고 있습니다.
이제 모델은 몇 시간 동안 실행되며, 야심찬 다중 파일 리팩터링을 완료하고, 테스트가 통과할 때까지 반복할 수 있습니다. 하지만 에이전트를 최대한 활용하려면 에이전트가 어떻게 작동하는지 이해하고 새로운 패턴을 개발해야 합니다.
이 가이드는 Cursor의 에이전트와 함께 작업하는 기법을 다룹니다. 에이전트 기반 코딩이 처음이든, 우리 팀이 Cursor를 사용하는 방식이 궁금하든, 에이전트와 함께 코딩할 때의 모범 사례를 살펴보겠습니다.
에이전트 하네스는 세 가지 구성요소로 이루어집니다.
Cursor의 에이전트 하네스는 우리가 지원하는 각 모델에 대해 이 구성요소들을 조율합니다. 내부 평가와 외부 벤치마크를 바탕으로 모든 최전선(frontier) 모델에 맞게 지침을 튜닝하고 도구를 조정합니다.
하네스가 중요한 이유는 같은 프롬프트라도 모델마다 반응이 다르기 때문입니다. 셸 중심 워크플로에 많이 훈련된 모델은 전용 검색 도구보다 grep을 선호할 수 있습니다. 또 다른 모델은 편집 후 린터 도구를 호출하라는 명시적 지침이 필요할 수 있습니다. Cursor의 에이전트는 이런 차이를 대신 처리해주므로, 새로운 모델이 출시되더라도 여러분은 소프트웨어를 만드는 일에 집중할 수 있습니다.
가장 큰 효과를 내는 변화는 코딩 전에 계획을 세우는 것입니다.
시카고 대학교의 연구에 따르면, 숙련된 개발자일수록 코드를 생성하기 전에 계획을 세울 가능성이 더 높습니다. 계획은 무엇을 만들고 있는지에 대한 명확한 사고를 강제하고, 에이전트가 달성해야 할 구체적인 목표를 제공합니다.
에이전트 입력창에서 Shift+Tab을 눌러 Plan Mode를 토글할 수 있습니다. 즉시 코드를 작성하는 대신 에이전트는 다음을 수행합니다.
Plan Mode 실행 예: 에이전트가 확인 질문을 하고 검토 가능한 계획을 만듭니다.
계획은 직접 편집할 수 있는 Markdown 파일로 열립니다. 불필요한 단계를 제거하거나, 접근 방식을 조정하거나, 에이전트가 놓친 맥락을 추가할 수 있습니다.
팁: “Save to workspace”를 클릭해 계획을
.cursor/plans/에 저장하세요. 팀을 위한 문서가 생기고, 중단된 작업을 쉽게 재개할 수 있으며, 같은 기능을 다루는 이후 에이전트에게도 맥락을 제공할 수 있습니다.
모든 작업에 상세한 계획이 필요한 것은 아닙니다. 빠른 변경이나 이미 여러 번 해본 작업이라면 곧바로 에이전트를 사용하는 것도 괜찮습니다.
가끔 에이전트가 만든 결과가 원하는 것과 다를 수 있습니다. 후속 프롬프트로 억지로 고치기보다는 계획으로 되돌아가세요.
변경사항을 되돌리고, 계획을 더 구체적으로 다듬은 다음 다시 실행하세요. 진행 중인 에이전트를 수정하는 것보다 종종 더 빠르며, 결과도 더 깔끔해집니다.
에이전트가 코드를 작성하는 것에 익숙해질수록, 여러분의 역할은 각 에이전트가 작업을 완료하는 데 필요한 컨텍스트를 제공하는 것이 됩니다.
프롬프트에서 모든 파일을 수동으로 태그할 필요는 없습니다.
Cursor의 에이전트는 강력한 검색 도구를 갖추고 있고 필요할 때 컨텍스트를 가져옵니다. “인증 플로우(authentication flow)”에 대해 물으면, 프롬프트에 정확히 그 단어가 없더라도 grep과 시맨틱 검색을 통해 관련 파일을 찾아냅니다.
인스턴트 grep은 에이전트가 코드베이스를 밀리초 단위로 검색할 수 있게 해줍니다.
단순하게 접근하세요. 정확한 파일을 알고 있다면 태그하고, 모른다면 에이전트가 찾게 두면 됩니다. 관련 없는 파일을 포함하면 무엇이 중요한지 에이전트를 혼란스럽게 만들 수 있습니다.
Cursor의 에이전트에는 @Branch 같은 유용한 도구도 있어, 여러분이 무엇을 작업 중인지에 대한 컨텍스트를 제공할 수 있습니다. “이 브랜치의 변경사항을 리뷰해줘” 또는 “내가 지금 뭘 작업하고 있어?” 같은 질문은 현재 작업을 기준으로 에이전트를 자연스럽게 정렬(오리엔테이션)해줍니다.
가장 흔한 질문 중 하나는 “이 대화를 계속 이어갈까, 아니면 새로 시작할까?”입니다.
다음 경우에는 새 대화를 시작하세요:
다음 경우에는 대화를 이어가세요:
긴 대화는 에이전트의 집중력을 떨어뜨릴 수 있습니다. 많은 턴과 요약을 거치면서 컨텍스트에 잡음이 쌓이고, 에이전트가 산만해지거나 관련 없는 작업으로 전환할 수 있습니다. 에이전트의 효율이 떨어진다고 느끼면 새 대화를 시작할 때입니다.
새 대화를 시작할 때는 전체 대화를 복사/붙여넣기 하는 대신 @Past Chats로 이전 작업을 참조하세요. 에이전트는 채팅 기록에서 필요한 컨텍스트만 선택적으로 읽어올 수 있습니다.
이는 대화를 통째로 중복하는 것보다 더 효율적입니다.

Cursor는 에이전트 동작을 커스터마이즈하는 두 가지 주요 방법을 제공합니다. 모든 대화에 적용되는 정적 컨텍스트를 위한 Rules, 그리고 필요할 때 에이전트가 사용할 수 있는 동적 기능을 위한 Skills입니다.
Rules는 에이전트가 여러분의 코드와 함께 일하는 방식을 형성하는 지속적인 지침입니다. 모든 대화 시작 시 에이전트가 항상 보는 ‘상시 컨텍스트(always-on context)’로 생각하면 됩니다.
.cursor/rules/에 Markdown 파일로 rules를 만드세요.
# Commands
- `npm run build`: 프로젝트 빌드
- `npm run typecheck`: 타입체커 실행
- `npm run test`: 테스트 실행(속도를 위해 단일 테스트 파일을 선호)
# Code style
- CommonJS(require) 대신 ES modules(import/export) 사용
- 가능하면 import를 구조 분해: `import { foo } from 'bar'`
- 표준 컴포넌트 구조는 `components/Button.tsx` 참고
# Workflow
- 일련의 코드 변경 후에는 항상 타입체크 수행
- API 라우트는 기존 패턴을 따라 `app/api/`에 위치
Rules는 핵심만 담아 간결하게 유지하세요. 실행해야 할 명령, 따라야 할 패턴, 코드베이스의 표준 예시(캐노니컬 예시)에 대한 포인터가 적절합니다. 파일 내용을 통째로 복사하기보다는 파일을 참조하세요. 이렇게 하면 rules가 짧아지고, 코드 변경에 따라 stale(구식)해지는 것을 방지할 수 있습니다.
Rules에서 피해야 할 것:
팁: 단순하게 시작하세요. 에이전트가 같은 실수를 반복한다고 느낄 때만 rules를 추가하세요. 패턴을 이해하기 전에 과도하게 최적화하지 마세요.
Rules는 git에 커밋해 팀 전체가 혜택을 보게 하세요. 에이전트가 실수하는 것을 보면 rule을 업데이트하세요. GitHub 이슈나 PR에서 @cursor를 태그하면 에이전트가 rule을 업데이트하도록 할 수도 있습니다.
Agent Skills는 에이전트가 할 수 있는 일을 확장합니다. Skills는 도메인별 지식, 워크플로, 스크립트를 패키징해, 관련될 때 에이전트가 호출할 수 있게 합니다.
Skills는 SKILL.md 파일로 정의되며 다음을 포함할 수 있습니다.
/로 트리거하는 재사용 가능한 워크플로Rules가 항상 포함되는 것과 달리, Skills는 에이전트가 관련 있다고 판단할 때 동적으로 로드됩니다. 이를 통해 컨텍스트 윈도우를 깨끗하게 유지하면서도, 에이전트가 특화된 기능에 접근할 수 있습니다.
강력한 패턴 중 하나는 skills를 이용해 목표를 달성할 때까지 오랜 시간 실행되며 반복하는 에이전트를 만드는 것입니다. 예를 들어 모든 테스트가 통과할 때까지 에이전트가 계속 작업하도록 만드는 훅을 만들 수 있습니다.
먼저 .cursor/hooks.json에 훅을 설정합니다.
{
"version": 1,
"hooks": {
"stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
}
}
훅 스크립트(.cursor/hooks/grind.ts)는 stdin으로부터 컨텍스트를 받고, 루프를 계속하기 위한 followup_message를 반환합니다.
import { readFileSync, existsSync } from "fs";
interface StopHookInput {
conversation_id: string;
status: "completed" | "aborted" | "error";
loop_count: number;
}
const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;
if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
console.log(JSON.stringify({}));
process.exit(0);
}
const scratchpad = existsSync(".cursor/scratchpad.md")
? readFileSync(".cursor/scratchpad.md", "utf-8")
: "";
if (scratchpad.includes("DONE")) {
console.log(JSON.stringify({}));
} else {
console.log(JSON.stringify({
followup_message: `[Iteration ${input.loop_count + 1}/${MAX_ITERATIONS}] Continue working. Update .cursor/scratchpad.md with DONE when complete.`
}));
}
이 패턴은 다음에 유용합니다.
팁: 훅이 포함된 Skills는 보안 도구, 시크릿 매니저, 관측(Observability) 플랫폼과 통합될 수 있습니다. 파트너 통합은 hooks 문서를 참고하세요.
Agent Skills는 현재 nightly 릴리스 채널에서만 사용할 수 있습니다. Cursor 설정을 열고 Beta를 선택한 다음 업데이트 채널을 Nightly로 설정하고 재시작하세요.
코딩을 넘어, 에이전트를 여러분이 매일 사용하는 다른 도구와도 연결할 수 있습니다. MCP(Model Context Protocol)를 사용하면 에이전트가 Slack 메시지를 읽고, Datadog 로그를 조사하고, Sentry의 에러를 디버깅하고, 데이터베이스를 쿼리하는 등 다양한 작업을 할 수 있습니다.
에이전트는 프롬프트에 포함된 이미지를 직접 처리할 수 있습니다. 스크린샷을 붙여넣거나, 디자인 파일을 드래그하거나, 이미지 경로를 참조하세요.
디자인 목업을 붙여넣고 구현을 요청하세요. 에이전트는 이미지를 보고 레이아웃, 색상, 간격을 맞출 수 있습니다. Figma MCP 서버도 사용할 수 있습니다.
에러 상태나 예상치 못한 UI를 스크린샷으로 찍어 에이전트에게 조사해 달라고 하세요. 문제를 말로 설명하는 것보다 빠른 경우가 많습니다.
에이전트는 브라우저를 제어해 자체적으로 스크린샷을 찍고, 애플리케이션을 테스트하며, 시각적 변경을 검증할 수도 있습니다. 자세한 내용은 Browser 문서를 참고하세요.
브라우저 사이드바를 사용하면 디자인과 코딩을 동시에 진행할 수 있습니다.
다양한 유형의 작업 전반에서 잘 작동하는 에이전트 패턴을 소개합니다.
에이전트는 코드를 작성하고, 테스트를 실행하고, 자동으로 반복할 수 있습니다.
에이전트는 반복할 명확한 목표가 있을 때 가장 잘 수행합니다. 테스트는 에이전트가 변경을 수행하고 결과를 평가하며, 성공할 때까지 점진적으로 개선할 수 있게 해줍니다.
새 코드베이스에 온보딩할 때, 학습과 탐색을 위해 에이전트를 사용하세요. 동료에게 묻는 것과 같은 질문을 던지면 됩니다.
CustomerOnboardingFlow는 어떤 엣지 케이스를 처리하나요?”createUser() 대신 setUser()를 호출하나요?”에이전트는 grep과 시맨틱 검색을 모두 사용해 코드베이스를 뒤지고 답을 찾습니다. 익숙하지 않은 코드에 빠르게 적응하는 가장 빠른 방법 중 하나입니다.
에이전트는 git 히스토리를 검색하고, 머지 충돌을 해결하며, git 워크플로를 자동화할 수 있습니다.
예를 들어, 커밋/푸시/PR 생성까지 해주는 /pr 커맨드:
현재 변경사항에 대해 Pull Request를 생성해줘.
1. `git diff`로 스테이징/비-스테이징 변경사항을 확인
2. 변경 내용을 바탕으로 명확한 커밋 메시지 작성
3. 현재 브랜치에 커밋하고 푸시
4. `gh pr create`로 제목/설명이 포함된 PR 열기
5. 완료되면 PR URL을 반환
명령(Commands)은 하루에도 여러 번 실행하는 워크플로에 적합합니다. .cursor/commands/에 Markdown 파일로 저장하고 git에 커밋해 팀 전체가 사용하게 하세요.
우리가 사용하는 다른 커맨드 예시:
/fix-issue [number]: gh issue view로 이슈 정보를 가져오고, 관련 코드를 찾아 수정한 뒤 PR 오픈/review: 린터 실행, 흔한 문제 확인, 주의가 필요한 부분 요약/update-deps: 오래된 의존성을 확인하고 하나씩 업데이트하며, 각 단계 후 테스트 실행에이전트는 이런 커맨드를 자율적으로 사용할 수 있으므로, / 한 번으로 다단계 워크플로를 위임할 수 있습니다.
AI가 생성한 코드는 리뷰가 필요하며, Cursor는 여러 옵션을 제공합니다.
에이전트가 작업하는 과정을 지켜보세요. diff 뷰는 변경사항을 실시간으로 보여줍니다. 에이전트가 잘못된 방향으로 가는 것 같다면 Escape를 눌러 중단하고 방향을 다시 제시하세요.
에이전트가 끝나면 Review → Find Issues를 클릭해 전용 리뷰 패스를 실행하세요. 에이전트가 제안된 수정사항을 라인 단위로 분석하고 잠재적인 문제를 표시합니다.
로컬의 모든 변경사항에 대해서는 Source Control 탭을 열고, 메인 브랜치와 비교하도록 Agent Review를 실행하세요.
AI 코드 리뷰는 Cursor 안에서 버그를 찾아 고칩니다.
소스 컨트롤에 푸시하면 Pull Request에 대해 자동 리뷰를 받을 수 있습니다. Bugbot은 고급 분석을 적용해 이슈를 조기에 잡고, 모든 PR에서 개선점을 제안합니다.
중요한 변경의 경우 에이전트에게 아키텍처 다이어그램 생성을 요청하세요. 예를 들어 이렇게 프롬프트를 줄 수 있습니다. “OAuth 제공자, 세션 관리, 토큰 갱신을 포함해 인증 시스템의 데이터 흐름을 보여주는 Mermaid 다이어그램을 만들어줘.” 이런 다이어그램은 문서화에 유용하고, 코드 리뷰 전에 아키텍처 문제를 드러내기도 합니다.
Cursor는 여러 에이전트를 서로 간섭 없이 병렬로 실행하기 쉽게 만들어줍니다. 같은 문제를 여러 모델에 시도하게 한 다음 최선의 결과를 선택하면, 특히 어려운 작업에서 최종 산출물이 크게 좋아진다는 것을 확인했습니다.
Cursor는 병렬 에이전트를 위해 git worktree를 자동으로 생성하고 관리합니다. 각 에이전트는 파일과 변경사항이 분리된 자체 worktree에서 실행되므로, 서로 발을 밟지 않고 편집/빌드/테스트를 수행할 수 있습니다.
worktree에서 에이전트를 실행하려면 에이전트 드롭다운에서 worktree 옵션을 선택하세요. 에이전트가 끝나면 Apply를 클릭해 변경사항을 작업 중인 브랜치에 병합합니다.
강력한 패턴은 같은 프롬프트를 여러 모델에 동시에 실행하는 것입니다. 드롭다운에서 여러 모델을 선택하고 프롬프트를 제출한 뒤 결과를 나란히 비교하세요. Cursor는 어떤 솔루션이 최선인지도 추천해줍니다.

이는 특히 다음에 유용합니다.
많은 에이전트를 병렬로 실행할 때는 완료 시점을 알 수 있도록 알림과 사운드를 설정하세요.
클라우드 에이전트는 보통 투두 리스트에 추가해두는 작업에 잘 맞습니다.
작업에 따라 로컬 에이전트와 클라우드 에이전트를 전환할 수 있습니다. 클라우드 에이전트는 cursor.com/agents, Cursor 에디터, 또는 휴대폰에서 시작할 수 있습니다. 자리를 비운 동안 웹이나 모바일에서 세션을 확인할 수도 있습니다. 클라우드 에이전트는 원격 샌드박스에서 실행되므로, 노트북을 닫고 나중에 결과를 확인할 수 있습니다.

cursor.com/agents에서 여러 클라우드 에이전트 관리하기
클라우드 에이전트가 내부적으로 동작하는 방식은 다음과 같습니다.
팁: Slack에서 “@Cursor”로 에이전트를 트리거할 수 있습니다. 자세히 알아보기.
일반적인 에이전트 상호작용으로 버그가 잘 해결되지 않을 때, Debug Mode는 다른 접근을 제공합니다.
추측으로 수정하는 대신, Debug Mode는 다음을 수행합니다.

이는 특히 다음에 잘 맞습니다.
핵심은 재현 방법에 대한 자세한 컨텍스트를 제공하는 것입니다. 더 구체적일수록 에이전트가 더 유용한 계측을 추가합니다.
에이전트로부터 가장 큰 가치를 얻는 개발자들은 몇 가지 공통점이 있습니다.
구체적인 프롬프트를 작성합니다. 구체적인 지침을 줄수록 에이전트의 성공률은 크게 올라갑니다. “auth.ts에 테스트 추가해줘”와 “__tests__/의 패턴을 사용해 로그아웃 엣지 케이스를 커버하는 auth.ts 테스트 케이스를 작성하고, 목은 피하라”를 비교해 보세요.
세팅을 반복적으로 다듬습니다. 단순하게 시작하세요. 에이전트가 같은 실수를 반복할 때만 rules를 추가하세요. 반복하고 싶은 워크플로가 정해진 뒤에야 commands를 추가하세요. 패턴을 이해하기 전에 과도하게 최적화하지 마세요.
꼼꼼히 리뷰합니다. AI 생성 코드는 겉보기엔 맞아 보여도 미묘하게 틀릴 수 있습니다. diff를 읽고 주의 깊게 리뷰하세요. 에이전트가 빠르게 작업할수록 리뷰 프로세스는 더 중요해집니다.
검증 가능한 목표를 제공합니다. 에이전트는 무엇이 문제인지 모르면 고칠 수 없습니다. 정적 타입 언어를 쓰고, 린터를 설정하고, 테스트를 작성하세요. 변경이 올바른지에 대한 명확한 신호를 에이전트에 제공하세요.
에이전트를 유능한 협업자로 대합니다. 계획을 요청하세요. 설명을 요구하세요. 마음에 들지 않는 접근에는 반론을 제기하세요.
에이전트는 빠르게 개선되고 있습니다. 최신 모델이 나오면 패턴도 진화하겠지만, 이 글이 오늘 코딩 에이전트와 함께 작업할 때 더 생산적으로 일하는 데 도움이 되길 바랍니다.
이 기법들을 직접 써보려면 Cursor의 에이전트로 시작해 보세요.