Cursor 에이전트 활용 가이드: 코딩 에이전트를 유능한 협업자로 만드는 방법

섹션별 상세

01

에이전트 하네스(Harness)는 시스템 프롬프트, 도구, 사용자 메시지를 오케스트레이션하여 각 모델에 최적화된 행동을 유도한다. Cursor는 내부 평가와 벤치마크를 바탕으로 각 프론티어 모델이 검색 도구나 터미널 명령을 가장 효과적으로 사용하도록 지침을 튜닝하며, 사용자는 모델의 특성을 고민할 필요 없이 빌드에만 집중할 수 있다.

02

계획 모드(Plan Mode)는 코드를 작성하기 전 코드베이스를 연구하고 상세한 구현 계획을 Markdown으로 생성하여 사용자 승인을 받는 단계이다. `Shift+Tab`으로 활성화하며, 생성된 계획은 `.cursor/plans/`에 저장되어 팀원 간의 문서화나 중단된 작업의 재개 시 중요한 컨텍스트로 활용된다.

03

컨텍스트 관리는 에이전트의 효율성을 결정짓는 핵심 요소로, 에이전트는 grep과 시맨틱 검색을 통해 필요한 파일을 스스로 찾아낸다. 불필요한 파일을 과도하게 태그하면 에이전트가 혼란을 겪을 수 있으므로, 작업 단위가 바뀌거나 에이전트의 성능이 저하될 때는 새로운 대화를 시작하고 `@Past Chats`로 필요한 맥락만 선택적으로 참조하는 것이 권장된다.

@Past Chats 기능을 통해 이전 대화 목록에서 컨텍스트를 선택적으로 가져오는 화면이다. — Screenshot새로운 대화를 시작할 때 이전 대화의 맥락을 효율적으로 재사용하는 방법을 보여준다. 이를 통해 컨텍스트 윈도우를 깨끗하게 유지하면서 필요한 정보만 에이전트에게 전달할 수 있음을 시각화한다.

04

Rules와 Skills를 통해 에이전트의 행동을 프로젝트에 맞게 커스터마이징할 수 있다. `.cursor/rules/`의 Markdown 파일은 모든 대화에 적용되는 정적 규칙(코드 스타일, 명령어 등)을 정의하며, `Skills`는 특정 상황에서 동적으로 로드되는 기능으로 테스트 통과 시까지 반복 실행되는 후크(Hooks) 등을 구현하는 데 사용된다.

markdown

# Commands
- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests

# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: `import { foo } from 'bar'`

# Workflow
- Always typecheck after making a series of code changes

.cursor/rules/ 파일에 정의하여 에이전트에게 프로젝트 고유의 규칙을 전달하는 예시

json

{
  "version": 1,
  "hooks": {
    "stop": [{
      "command": "bun run .cursor/hooks/grind.ts"
    }]
  }
}

에이전트 작업이 멈췄을 때 특정 스크립트를 실행하도록 설정하는 후크 구성

typescript

import { readFileSync, existsSync } from "fs";
// ...(중략)
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.`
  }));
}

테스트가 통과할 때까지 에이전트를 반복 실행시키는 루프 제어 스크립트

05

TDD(테스트 주도 개발) 패턴은 에이전트에게 명확한 목표를 제공하여 성능을 높인다. 에이전트에게 테스트를 먼저 작성하게 하고, 이를 통과할 때까지 구현 코드를 반복 수정하게 함으로써 점진적이고 안정적인 코드 생성이 가능하다.

06

병렬 실행과 Native Worktree 지원을 통해 여러 모델이 동일한 문제를 동시에 해결하게 하고 최적의 결과를 선택할 수 있다. 각 에이전트는 격리된 워크트리에서 독립적으로 빌드와 테스트를 수행하며, 사용자는 여러 모델의 제안을 나란히 비교하여 가장 우수한 코드를 적용할 수 있다.

여러 모델이 생성한 해결책을 비교하고 Cursor가 최적의 안을 추천하는 멀티 에이전트 판단 화면이다. — Screenshot병렬로 실행된 여러 모델(GPT-5.1, Opus 4.5 등)의 코드 수정량과 성공 여부를 한눈에 비교할 수 있음을 보여준다. 복잡한 문제에서 최적의 모델 결과물을 선택하는 워크플로우를 설명한다.

진행 중인 에이전트 작업들을 칸반 보드 형태로 관리하는 대시보드 화면이다. — Screenshot여러 에이전트가 수행 중인 코딩 및 조사 작업의 상태를 시각적으로 추적할 수 있음을 보여준다. 클라우드 에이전트를 통해 병렬로 여러 작업을 위임하고 관리하는 방식을 설명한다.

07

디버그 모드(Debug Mode)는 단순한 수정을 넘어 가설 수립, 로깅 코드 삽입, 런타임 데이터 수집 및 분석을 통해 복잡한 버그의 근본 원인을 파악한다. 레이스 컨디션이나 성능 문제처럼 재현은 가능하지만 원인 파악이 어려운 문제 해결에 특히 유용하다.

에이전트 모드 선택 드롭다운에서 Debug Mode를 선택하는 화면이다. — Screenshot일반적인 에이전트 작업 외에 디버깅에 특화된 모드를 선택할 수 있는 UI를 보여준다. 까다로운 버그 해결을 위해 별도의 추론 및 계측 과정을 거치는 디버그 모드의 접근성을 확인시켜 준다.

용어 해설

에이전트 하네스(Agent Harness): — 에이전트의 행동을 제어하기 위해 시스템 프롬프트, 도구 세트, 사용자 입력을 결합하고 조율하는 아키텍처 프레임워크이다. 각 LLM 모델의 특성에 맞춰 최적화된 지침을 제공함으로써 모델이 코드베이스 검색이나 터미널 실행 등의 도구를 가장 효과적으로 사용하도록 돕는 역할을 수행한다.
계획 모드(Plan Mode): — 코드를 즉시 작성하기 전에 에이전트가 코드베이스를 조사하고 구현 단계를 Markdown 형식으로 먼저 설계하는 워크플로우이다. 사용자는 에이전트가 제안한 계획을 검토하고 수정할 수 있으며, 승인된 계획에 따라 에이전트가 작업을 수행하게 함으로써 복잡한 작업의 정확도를 높이고 오작동을 방지한다.
모델 컨텍스트 프로토콜(MCP): — LLM 에이전트가 Slack, Sentry, Datadog 등 외부 데이터 소스 및 도구와 표준화된 방식으로 통신할 수 있게 해주는 개방형 프로토콜이다. 이를 통해 에이전트는 단순한 코드 작성을 넘어 실시간 로그 조사, 데이터베이스 쿼리, 메시지 확인 등 더 넓은 범위의 컨텍스트를 파악하고 작업을 수행할 수 있다.
워크트리(Worktree): — 하나의 Git 저장소에서 여러 개의 작업 디렉토리를 동시에 유지할 수 있게 해주는 Git의 기능이다. Cursor는 이를 활용해 여러 에이전트를 병렬로 실행하며, 각 에이전트가 서로의 작업을 방해하지 않고 독립된 환경에서 코드를 수정하고 테스트할 수 있도록 격리된 환경을 제공한다.
테스트 주도 개발(TDD): — 실제 코드를 작성하기 전에 테스트 케이스를 먼저 작성하고, 그 테스트를 통과하기 위한 최소한의 코드를 구현하는 개발 방법론이다. 에이전트에게 명확한 성공 기준(테스트 통과)을 제공하므로, 에이전트가 자율적으로 코드를 수정하고 검증하며 목표에 도달할 때까지 반복 작업하는 데 매우 효과적이다.