Cursor 실전 가이드

Cursor를 쓸 때 가장 먼저 정리해야 할 것은 세 가지 상호작용 모드의 용도 구분이다. 셋을 섞어 쓰면 빠르지만, 어떤 모드가 어떤 작업에 맞는지 모르면 에이전트로 한 줄 고치겠다고 컨텍스트를 통째로 태우거나, 자동완성으로 끝낼 일을 채팅으로 길게 끄는 비효율이 생긴다.

1) Tab (자동완성) — 타이핑하는 동안 다음 편집을 예측한다. 단순한 다음 토큰 예측이 아니라 여러 줄, 커서 이동, 다음 편집 위치까지 제안한다. 반복적인 보일러플레이트, 패턴이 명확한 코드(예: 비슷한 case 추가, 타입 정의 채우기)에 강하다. Tab으로 수락, Esc로 거절, 부분 수락은 보통 Ctrl/⌘ + →.

2) 인라인 편집 (⌘K / Ctrl+K) — 코드 일부를 선택하고 ⌘K를 누른 뒤 자연어로 지시하면, 선택 범위 안에서만 변경을 제안한다. diff로 보여주고 수락/거절을 고른다. 범위가 좁아 빠르고 예측 가능하다. "이 함수에 입력 검증 추가", "이 루프를 map으로" 같은 국소 변경에 최적. 선택 없이 ⌘K를 누르면 그 위치에 새 코드를 생성한다.

3) 에이전트 / Composer — 채팅 패널에서 자연어로 큰 작업을 맡기면, AI가 스스로 어떤 파일을 읽을지 정하고, 여러 파일을 생성·수정하고, 필요하면 터미널 명령까지 실행한다. "인증 미들웨어 추가하고 라우트에 적용해줘" 같은 멀티파일 기능 작업이 여기에 해당한다.

작업 크기에 따른 모드 선택
──────────────────────────────────────────────
한 줄~몇 줄, 패턴 명확        →  Tab
선택 범위 안 국소 변경        →  인라인 편집 (⌘K)
여러 파일·새 파일·명령 실행    →  에이전트 (Composer)

흔한 함정: 모든 걸 에이전트로 처리하려는 습관. 변수명 하나 바꾸는 작업에 에이전트를 부르면 코드베이스를 뒤지느라 토큰과 시간을 낭비하고, 의도치 않은 파일까지 건드릴 위험이 생긴다. 반대로, 5개 파일에 걸친 리팩터링을 ⌘K로 하나씩 처리하는 것도 비효율이다.

베스트 프랙티스: "국소적이고 내가 정확히 어디를 고칠지 아는가?" → ⌘K. "여러 곳에 걸쳐 있고 AI가 위치를 찾아야 하는가?" → 에이전트. 평소 타이핑 흐름은 Tab에 맡긴다.

에이전트(Composer)는 단순히 텍스트를 뱉는 게 아니라 도구를 호출하며 작업을 수행하는 루프다. 내부적으로 다음 사이클을 돈다.

1. 계획 — 요청을 분석해 어떤 단계가 필요한지 정한다.
2. 컨텍스트 수집 — 코드베이스를 검색(semantic search)하고, 관련 파일을 읽고, 디렉터리 구조를 파악한다. 당신이 @로 명시하지 않아도 스스로 끌어온다.
3. 편집/실행 — 파일을 생성·수정하고, 필요하면 터미널 명령(npm install, 테스트 실행 등)을 제안하거나 실행한다.
4. 검토 대기 — 각 변경을 diff로 보여주고 사용자의 수락을 기다린다.

실무에서 중요한 건 이 루프의 어느 지점에 개입하느냐다.

도구 실행 승인 정책 — 터미널 명령 실행은 위험할 수 있으므로, Cursor는 명령마다 승인을 요구하거나(기본), 신뢰하는 명령을 자동 실행하도록 설정할 수 있다. 설정에서 자동 실행을 켜되, 화이트리스트/블랙리스트로 통제하는 것이 안전하다. 예를 들어 git push, rm -rf, curl ... | sh 같은 파괴적·외부 명령은 절대 자동 실행에서 제외하라.

# 자동 실행을 켜더라도 반드시 차단해야 할 명령 패턴 예시
rm -rf            # 파괴적 삭제
git push --force  # 히스토리 덮어쓰기
curl|sh, wget|sh  # 외부 스크립트 즉시 실행
npm publish       # 배포
drop table, truncate  # DB 파괴

좋은 프롬프트 vs 나쁜 프롬프트 — 에이전트는 모호한 지시에 약하다.

나쁨:  "로그인 고쳐줘"
좋음:  "src/auth/login.ts 의 signIn 함수에서, 비밀번호가
        틀렸을 때 401 대신 500을 던지는 버그가 있어.
        Supabase 에러 코드를 매핑해서 401/422로 구분해줘.
        기존 에러 핸들링 패턴은 lib/api-error.ts 를 따라."

좋은 프롬프트는 (a) 변경 대상 파일/함수, (b) 현재 증상, (c) 기대 동작, (d) 따라야 할 기존 패턴을 명시한다.

함정: 에이전트가 한 번에 너무 많은 걸 하게 두면 diff가 검토 불가능한 크기로 불어난다. 그러면 실수를 놓치고 통째로 수락하게 된다. 작업을 의미 단위로 쪼개서, 한 사이클당 검토 가능한 분량(보통 2~5개 파일)으로 유지하라.

베스트 프랙티스: 큰 작업은 먼저 "구현하지 말고 계획만 세워줘"로 계획을 받고, 계획을 검토·수정한 뒤 "이제 1단계만 구현해"로 단계별 실행한다. 이것이 Plan → Work → Review 루프를 에이전트에 적용하는 방식이다.

Cursor 출력 품질의 80%는 컨텍스트에 무엇이 들어갔느냐로 결정된다. 채팅 입력창에서 @를 누르면 컨텍스트로 주입할 항목 목록이 뜬다. 핵심 심볼들:

심볼	주입되는 것	언제 쓰나
@Files	특정 파일 전체	이 파일을 반드시 보게 하고 싶을 때
@Folders	폴더 안 파일들	모듈/기능 단위로 맥락 줄 때
@Code	특정 심볼(함수/클래스)	파일 전체는 과한데 함수만 필요할 때
@Docs	인덱싱된 라이브러리 문서	프레임워크 API 정확도 필요
@Web	실시간 웹 검색	최신 정보·에러 메시지 검색
@Git	커밋/diff	변경 이력 기반 작업
@Past Chats	이전 대화	맥락 이어받기

코드베이스 인덱싱 — Cursor는 프로젝트를 열면 코드를 청크로 나눠 임베딩하고 벡터 인덱스를 만든다. 덕분에 에이전트가 @로 명시하지 않은 파일도 의미 기반으로 찾아낸다("인증 관련 코드 찾아"가 작동하는 이유). 큰 모노레포에서는 첫 인덱싱에 시간이 걸리고, .cursorignore로 인덱싱 제외 범위를 지정할 수 있다.

# .cursorignore — 인덱싱/컨텍스트에서 제외
node_modules/
dist/
build/
*.min.js
*.lock
coverage/
.next/
# 대용량 생성물·시드 데이터
public/uploads/
data/fixtures/*.json

@Docs 등록 — 자주 쓰는 라이브러리 공식 문서 URL을 등록하면, 모델이 환각으로 API를 지어내는 대신 실제 문서를 참조한다. 빠르게 바뀌는 프레임워크(Next.js, Tailwind 등)에서 특히 효과가 크다. 설정에서 문서 URL을 추가하면 Cursor가 크롤링·인덱싱한다.

함정 1 — 컨텍스트 과주입: "확실하게" 한다고 @Folders로 폴더 전체를 통째로 넣으면, 관련 없는 파일이 컨텍스트를 잠식해 모델 정확도가 오히려 떨어지고 비용이 치솟는다. 필요한 파일만 @Files/@Code로 좁혀라.

함정 2 — 인덱싱 신뢰 과신: 시맨틱 검색은 만능이 아니다. 정확히 그 파일을 봐야 하는 작업이면 @로 명시적으로 고정하라. "알아서 찾겠지"는 큰 변경에서 누락을 만든다.

베스트 프랙티스: 프롬프트에 변경 대상은 @Files로 고정, 참조할 패턴은 @Code로 함수만, 외부 API는 @Docs로 — 이렇게 컨텍스트를 '정밀하게' 구성한다. 넓게 던지지 말고 좁게 조준하라.

규칙(Rules)은 모든 대화에 반복 주입되는 영구 지침이다. 매번 "우리 프로젝트는 한국어 주석 써", "에러는 lib/api-error.ts 패턴 따라"를 적지 않아도 되게 만든다. 2026년 기준 권장 방식은 프로젝트 루트의 .cursor/rules/ 디렉터리에 .mdc 파일로 두는 것이다.

중요: 구버전의 단일 .cursorrules 파일은 여전히 동작하지만 에이전트 모드에서 조용히 무시되는 경우가 보고된다. 에이전트 워크플로우를 쓴다면 .cursor/rules/*.mdc로 마이그레이션하라. (출처)

MDC 파일은 YAML 프론트매터 + 마크다운 본문 구조다. 프론트매터의 세 필드가 규칙의 활성화 방식을 결정한다.

---
description: API 라우트 작성 규칙 (에러 핸들링, 응답 형식)
globs: src/app/api/**/*.ts
alwaysApply: false
---

# API 라우트 규칙

- 모든 핸들러는 try/catch로 감싸고, 에러는 `lib/api-error.ts`의
  `toApiError()`로 변환해 반환한다. 직접 NextResponse.json 으로
  에러 본문을 만들지 말 것.
- 요청 본문 검증은 zod 스키마로. 검증 실패는 422로 반환.
- 성공 응답은 `{ data, error: null }` 형태로 통일.

## 참고 패턴
@lib/api-error.ts
@src/app/api/users/route.ts

프론트매터 필드 정리 (Cursor Docs):

필드	의미
description	규칙의 목적. 에이전트가 이 설명을 보고 규칙을 끌어올지 판단(Agent Requested)
globs	이 패턴에 매칭되는 파일을 열거나 편집할 때 자동 첨부
alwaysApply	true면 모든 대화에 항상 주입

본문의 @파일 참조 — 본문에 @lib/api-error.ts처럼 적으면 규칙이 적용될 때 해당 파일이 컨텍스트에 함께 들어간다. 템플릿이나 모범 예시 파일을 가리키게 해서, 규칙 텍스트에 코드를 복붙하지 않고도 에이전트가 실제 패턴을 보게 만든다.

중요 — plain .md는 무시된다: .cursor/rules에 프론트매터 없는 .md 파일을 두면 규칙 시스템이 인식하지 못한다. 반드시 .mdc 확장자와 프론트매터를 갖춰라.

규칙 자동 생성 — 채팅에서 /Generate Cursor Rules(또는 유사한 슬래시 명령)를 쓰면, 현재 대화 맥락에서 규칙 파일을 프론트매터까지 갖춰 자동 생성해 .cursor/rules에 저장한다. 반복되는 지시를 발견하면 이걸로 규칙화하라.

베스트 프랙티스: 규칙은 짧고 구체적으로. 한 파일에 모든 걸 욱여넣지 말고 도메인별로 쪼갠다(api 규칙, 컴포넌트 규칙, 테스트 규칙). 그래야 glob/description으로 필요한 것만 정확히 붙는다.

MDC 프론트매터 조합에 따라 규칙은 네 가지 방식으로 활성화된다. 이 선택을 잘못하면 토큰을 낭비하거나(항상 주입), 정작 필요할 때 규칙이 안 붙는다(잘못된 모드). Cursor Docs 기준:

모드	프론트매터	동작	적합한 규칙
Always	alwaysApply: true	모든 대화에 무조건 주입	프로젝트 전역 컨벤션(언어, 톤)
Auto Attached	globs: ...	매칭 파일 열/편집 시 자동	파일 타입별 규칙(*.tsx, api/**)
Agent Requested	description + alwaysApply: false	에이전트가 설명 보고 필요 판단 시 끌어옴	특정 작업용 규칙(배포, 마이그레이션)
Manual	(조건 없음)	@규칙이름으로 직접 호출	가끔만 필요한 특수 규칙

Always — 짧게 유지하라: alwaysApply: true 규칙은 모든 메시지마다 토큰을 먹는다. 그래서 전역 규칙은 20줄 안팎으로 짧게 유지하는 게 정설이다. "코드 주석은 한국어", "any 타입 금지", "console.log 커밋 금지" 같은 보편 컨벤션만 넣어라. 긴 규칙을 Always로 두면 모든 대화의 컨텍스트 예산을 갉아먹는다.

---
alwaysApply: true
---
# 전역 컨벤션 (짧게!)
- 주석/문서 문자열은 한국어.
- TypeScript strict. `any` 금지, `unknown` + 좁히기 사용.
- 커밋 전 console.log/디버그 코드 제거.
- 새 의존성 추가 전 먼저 확인 요청.

Auto Attached — 파일 타입별 지식: 컴포넌트 파일을 열 때만 React 규칙이, API 파일을 열 때만 라우트 규칙이 붙게 한다. 가장 토큰 효율적이고 직관적이라 실무에서 제일 많이 쓰인다.

---
globs: src/components/**/*.tsx
alwaysApply: false
---
# React 컴포넌트 규칙
- 함수형 컴포넌트 + named export.
- props는 인터페이스로 명시, 인라인 타입 금지.
- 클라이언트 상태는 zustand, 서버 상태는 react-query.

Agent Requested — 설명이 생명: 이 모드는 에이전트가 description만 보고 규칙을 끌어올지 결정한다. 따라서 description을 언제 이 규칙이 필요한지 명확히 써야 한다. "마이그레이션 규칙"보다 "DB 스키마 변경·마이그레이션 SQL 작성 시 적용. RLS 정책과 인덱스 포함"이 훨씬 잘 선택된다.

함정: globs를 적었는데 alwaysApply: true로 같이 두는 실수. alwaysApply가 우선해서 항상 붙어버린다. Auto Attached를 원하면 alwaysApply: false로 두고 globs만 지정하라.

베스트 프랙티스: 규칙 대부분은 Auto Attached(globs)로. 전역은 최소한만 Always로. 가끔 쓰는 특수 절차는 Agent Requested 또는 Manual로. 이 배분이 토큰 예산과 정확도의 균형점이다.

.cursor/rules 외에 **AGENTS.md**라는 더 단순한 대안이 있다. 프로젝트 루트(또는 하위 디렉터리)에 두는 평범한 마크다운 파일로, 프론트매터 없이 에이전트 지침을 적는다. 이 형식의 장점은 에디터 중립적이라는 것 — 동일 파일을 여러 AI 코딩 도구가 공유 표준으로 읽는 흐름이 자리잡고 있어, 한 번 작성하면 도구를 바꿔도 재사용된다.

<!-- AGENTS.md (프로젝트 루트) -->
# 에이전트 작업 지침

## 빌드/테스트
- 설치: `pnpm install`
- 개발: `pnpm dev` (포트 3000)
- 테스트: `pnpm test` (Vitest), 단일 파일: `pnpm test path/to.test.ts`
- 린트: `pnpm lint --fix`

## 코드 컨벤션
- 패키지 매니저는 pnpm 고정 (npm/yarn 사용 금지).
- 절대 경로 import: `@/lib/...`
- 커밋 메시지: Conventional Commits (feat/fix/docs).

## 절대 하지 말 것
- main 브랜치 직접 push 금지. 항상 브랜치 생성 후 PR.
- .env, 시크릿 파일 수정 금지.

계층 구조와 우선순위 — 규칙은 여러 출처에서 합쳐진다. 대략적인 적용 순서/범위:

1. User Rules     — Cursor 설정의 개인 전역 규칙 (모든 프로젝트)
2. AGENTS.md      — 프로젝트 루트 (도구 중립 지침)
3. .cursor/rules/ — 프로젝트 규칙 (.mdc, 가장 세밀한 제어)
4. 하위 디렉터리   — 모노레포의 패키지별 규칙/AGENTS.md

모노레포 패턴 — 모노레포에서는 패키지마다 다른 규칙이 필요하다. packages/web/.cursor/rules/와 packages/api/.cursor/rules/를 따로 두면, 해당 디렉터리에서 작업할 때 그 규칙이 우선 적용된다. 루트에는 공통 규칙만, 패키지에는 패키지 고유 규칙만 두는 식으로 분리하라.

User Rules vs Project Rules — User Rules는 Cursor 설정에 저장되는 개인 취향(예: "설명은 짧게", "코드부터 보여줘")으로, 버전 관리되지 않고 모든 프로젝트에 적용된다. Project Rules는 레포에 커밋되어 팀이 공유한다. 개인 스타일은 User Rules에, 팀 표준은 Project Rules에 두는 게 원칙이다.

함정: .cursorrules(구), .cursor/rules/*.mdc(신), AGENTS.md를 동시에 어중간하게 섞어두면 어떤 게 적용되는지 추적이 안 된다. 하나의 주 방식을 정하고(권장: .cursor/rules), 나머지는 정리하라.

베스트 프랙티스: 빌드/테스트 명령처럼 "이 레포를 어떻게 돌리는가"는 AGENTS.md에, 코드 스타일·아키텍처 규약처럼 "어떻게 코드를 쓰는가"는 .cursor/rules에 — 역할을 나눠 두면 둘 다 짧고 명확해진다.

에이전트의 진짜 가치는 여러 파일을 한 번에 일관되게 바꾸는 것이다. "User 타입에 phone 필드 추가"라고 하면 타입 정의, 마이그레이션, 폼 컴포넌트, API 검증을 한 사이클에 수정한다. 문제는 이게 빠른 만큼 빠르게 망가뜨릴 수도 있다는 점이다. 그래서 diff 검토가 워크플로우의 핵심이다.

검토 흐름 — 에이전트가 변경을 만들면 파일별 diff가 표시된다. 각 변경에 대해:

• 파일 단위 수락/거절 — 일부 파일만 받고 일부는 버릴 수 있다.
• 전체 수락(Accept All) — diff가 작고 신뢰될 때만.
• 추가 지시 — "이 변경은 좋은데, B 파일은 기존 패턴이랑 안 맞아. 수정해"로 같은 대화에서 이어 고친다.

검토에서 반드시 확인할 것:

검토 체크리스트
──────────────────────────────────
□ 의도하지 않은 파일이 수정됐는가? (가장 위험)
□ 기존 패턴/네이밍을 따랐는가?
□ import가 올바른 위치에 추가됐는가?
□ 삭제된 코드가 정말 불필요한가? (과도한 삭제 주의)
□ 에러 핸들링·엣지 케이스가 빠지지 않았는가?
□ 타입이 좁혀졌는가, any/단언으로 회피했는가?

특히 의도하지 않은 파일 수정이 가장 위험하다. "로그인 고쳐줘"가 엉뚱하게 공통 유틸을 건드리면, 검토에서 잡지 못하면 다른 기능이 조용히 깨진다.

큰 리팩터링은 쪼개라 — 20개 파일을 한 번에 바꾸는 작업은 diff가 검토 불가능해진다. 의미 단위로 분할:

나쁨:  "전체 코드베이스를 zod v4로 마이그레이션해줘"

좋음:  단계별로 ──
  1단계: "먼저 zod import 패턴이 바뀐 곳 목록만 뽑아줘"
  2단계: "src/lib 의 스키마부터 마이그레이션. 다른 디렉터리는 손대지 마"
  3단계: (검토·커밋 후) "이제 src/app/api 차례"

각 단계 사이에 커밋을 끼워라. 그래야 다음 단계가 망가져도 git으로 깔끔히 되돌린다.

함정: "Accept All"의 습관화. 빠르다는 이유로 검토 없이 다 수락하면, 에이전트가 만든 미묘한 버그(부호 뒤집힘, 잘못된 import 위치, 누락된 await)가 그대로 머지된다. 빠른 도구일수록 사람의 검토가 병목이자 안전장치다.

베스트 프랙티스: 한 에이전트 사이클 = 한 의미 단위 = 한 커밋. diff가 한 화면을 크게 넘어가면 작업이 너무 컸다는 신호다. 다음엔 더 잘게 지시하라.

에이전트는 자율적이라 가끔 통제를 벗어나 코드를 크게 뒤엎는다. Cursor는 이를 위해 **체크포인트(Checkpoint)**를 제공한다. 에이전트가 큰 변경을 하기 전 상태를 자동으로 스냅샷하고, 채팅 타임라인에서 "Restore Checkpoint"로 그 시점으로 되돌릴 수 있다.

체크포인트 vs git — 둘은 다른 안전망이다.

	체크포인트	git
범위	Cursor 세션 내 변경	커밋된 모든 것
입도	에이전트 턴 단위	커밋 단위
지속성	세션/대화에 종속	영구
용도	"방금 그 시도 취소"	"검증된 상태로 복구"

체크포인트는 "에이전트가 방금 한 짓을 빠르게 무르기"용이고, git은 "확실히 동작하던 상태로 복귀"용이다. 둘 다 써야 한다.

안전한 실험 루틴:

1. 작업 시작 전 — git 상태 깨끗하게 (커밋 or stash)
2. 에이전트에 작업 지시
3. diff 검토 → 수락
4. 빌드/테스트 실행으로 검증
5. 잘 되면 git commit (= 새 안전 지점)
6. 망가졌으면:
   - 작은 실수 → 체크포인트 복구 or 추가 지시로 수정
   - 크게 꼬임 → git restore/checkout 으로 마지막 커밋 복귀

함정 1 — 검증 없는 진행: 에이전트가 "완료했습니다"라고 해도 그게 동작한다는 뜻이 아니다. 빌드가 통과하는지, 테스트가 녹색인지, 실제로 앱이 뜨는지 직접 확인해야 한다. AI의 완료 선언은 검증이 아니다.

함정 2 — 커밋 없이 길게 진행: 5개 작업을 커밋 없이 연속으로 시키면, 3번째에서 꼬였을 때 1·2번까지 통째로 날아간다. 검증된 단계마다 커밋해 안전 지점을 촘촘히 박아라.

함정 3 — 체크포인트를 git 대용으로 착각: 체크포인트는 대화/세션에 묶여 있어 영구적이지 않다. 다른 머신에서 이어받거나 며칠 뒤 복구해야 한다면 git만이 답이다.

베스트 프랙티스: "작업 전 깨끗한 git 상태 → 에이전트 → 검증 → 커밋"을 하나의 리듬으로 만들어라. 에이전트를 신뢰하되, 매 단계 검증과 커밋으로 신뢰를 뒷받침한다.

**MCP(Model Context Protocol)**는 AI가 외부 도구·데이터 소스와 표준화된 방식으로 통신하는 프로토콜이다. Cursor는 MCP 서버를 연결해 에이전트가 코드베이스 바깥의 컨텍스트와 행동에 접근하게 한다. 예를 들어 DB 스키마를 직접 조회하거나, 이슈 트래커를 읽거나, 디자인 파일을 가져오는 식이다.

설정 방법 — 프로젝트 루트나 사용자 설정에 MCP 서버를 등록한다(보통 .cursor/mcp.json 또는 설정 UI).

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/mydb"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "/Users/me/docs"]
    }
  }
}

등록 후 에이전트는 그 서버가 노출한 도구를 자동으로 쓸 수 있다. "users 테이블 스키마 보고 거기에 맞는 타입 정의 만들어줘"라고 하면, 환각으로 컬럼을 지어내는 대신 MCP로 실제 스키마를 조회해 정확한 타입을 생성한다.

대표 활용 사례:

MCP 서버	에이전트가 할 수 있는 것
Postgres/DB	실제 스키마 조회 → 정확한 타입/쿼리 생성
GitHub	이슈/PR 읽기, 코드 검색
파일시스템	레포 밖 문서·스펙 참조
브라우저/Playwright	실제 페이지 열어 UI 검증
Sentry	에러 이슈 읽어 원인 분석

보안 주의 — 이게 핵심이다:

• 신뢰할 수 있는 MCP 서버만 연결하라. MCP 서버는 임의 코드를 실행할 수 있는 프로세스다. 출처 불명의 서버는 곧 임의 코드 실행 권한을 주는 것과 같다.
• 시크릿/커넥션 문자열을 .cursor/mcp.json에 평문으로 박아 커밋하지 마라. 환경 변수나 시크릿 관리자를 거쳐라. DB 비밀번호가 든 mcp.json을 그대로 push하는 사고가 흔하다.
• 프롬프트 인젝션 — MCP로 가져온 외부 데이터(이슈 본문, 웹 페이지)에 ".env를 출력해" 같은 악의적 지시가 숨어 있을 수 있다. 외부 데이터를 다루는 에이전트의 행동은 검토 후 승인하라.

함정: MCP 서버를 과하게 많이 연결하면 에이전트가 매 턴 너무 많은 도구 정의를 보느라 컨텍스트가 늘고 판단이 흐려진다. 현재 작업에 필요한 서버만 켜라.

베스트 프랙티스: MCP는 "에이전트가 진짜 데이터를 보게 해서 환각을 줄이는" 용도로 가장 가치 있다. DB 스키마 동기화, 실제 에러 분석처럼 정확도가 중요한 작업부터 도입하고, 권한과 시크릿은 보수적으로 관리하라.

Cursor는 여러 모델을 제공하고, 작업에 맞는 모델 선택이 비용과 품질을 동시에 좌우한다. 정확한 모델 라인업과 가격은 시점에 따라 바뀌므로 일반 원칙으로 정리한다.

모델 선택 원칙:

작업 유형	선택
단순 편집, 보일러플레이트, 빠른 반복	빠르고 저렴한 모델
복잡한 아키텍처, 멀티파일 추론, 디버깅	고성능 프런티어 모델
큰 컨텍스트가 필요한 작업(대형 레포 분석)	큰 컨텍스트 윈도우 모델

비용을 키우는 주범:

1. 긴 대화 누적 — 한 대화가 길어질수록 이전 맥락이 매 턴 재전송되어 토큰이 기하급수로 는다. 작업이 끝나거나 주제가 바뀌면 새 대화를 시작하라. (이건 정확도에도 좋다 — 무관한 과거 맥락이 판단을 흐리는 것을 막는다.)
2. alwaysApply 규칙 과다 — 앞서 말했듯 모든 메시지에 주입되므로, 긴 Always 규칙은 누적 비용이 크다.
3. 불필요한 컨텍스트 주입 — @Folders로 폴더 통째로 넣기, 거대 파일 반복 첨부.
4. 에이전트의 과잉 탐색 — 모호한 지시에 에이전트가 코드베이스를 광범위하게 뒤지면 그만큼 읽기 토큰을 쓴다. 명확한 지시가 곧 비용 절감이다.

토큰 예산 절약 루틴:

- 주제 바뀌면 새 대화 (대화당 한 가지 작업)
- 변경 대상은 @로 명시 (에이전트 탐색 비용 절감)
- Always 규칙은 20줄 이하로 유지
- .cursorignore 로 인덱싱 범위 축소
- 단순 작업엔 빠른 모델, 어려운 작업에만 프런티어 모델

함정 1 — 무한정 이어가기: "맥락 살리려고" 한 대화에서 하루 종일 작업하면 토큰이 폭증하고 모델은 오래된 맥락에 끌려 엉뚱한 판단을 한다. 한 작업 = 한 대화가 비용·품질 양쪽에서 낫다.

함정 2 — 비싼 모델 디폴트화: 변수명 바꾸기에 최고 모델을 쓰는 건 낭비다. 작업 난이도에 맞춰 모델을 바꾸는 습관을 들여라.

베스트 프랙티스: "이 작업에 이만한 컨텍스트와 모델이 정말 필요한가?"를 매 작업 전 30초만 생각하라. 컨텍스트를 좁히고 대화를 짧게 유지하는 것이 비용 절감인 동시에 정확도 향상이다 — 이 둘은 같은 방향이다.

개인이 Cursor를 잘 쓰는 것과 팀 전체가 일관되게 쓰는 것은 다른 문제다. 규칙을 레포에 커밋해 공유하지 않으면, 같은 코드베이스인데도 사람마다 AI가 다른 스타일의 코드를 뱉어 일관성이 무너진다.

팀 표준화 체크리스트:

레포에 커밋해 공유해야 할 것
──────────────────────────────────
□ .cursor/rules/*.mdc   — 코드 컨벤션, 아키텍처 규약
□ AGENTS.md             — 빌드/테스트/실행 명령
□ .cursorignore         — 인덱싱 제외 (모두 동일하게)
□ .cursor/mcp.json      — 단, 시크릿은 env로 분리

커밋하지 말 것 (.gitignore)
──────────────────────────────────
□ 개인 User Rules        — Cursor 설정에 개인별
□ 시크릿이 박힌 mcp 설정

규칙은 점진적으로 축적하라. 에이전트가 같은 실수를 반복하거나, 코드 리뷰에서 같은 지적이 반복되면 → 그걸 규칙으로 박아라. 그러면 다음부터 그 실수가 사라진다. "리뷰에서 발견한 패턴 → 규칙화"는 매 작업이 다음 작업을 쉽게 만드는 복리 효과를 낸다.

백그라운드/병렬 에이전트 — 2026년 기준 Cursor는 여러 에이전트를 동시에 돌리거나(병렬), 클라우드에서 백그라운드로 작업을 수행하는 기능을 제공한다(출처). 서로 독립적인 작업(예: 문서 작성과 테스트 추가)을 병렬로 맡기면 처리량이 는다. 다만:

• 충돌 위험 — 두 에이전트가 같은 파일을 동시에 건드리면 변경이 꼬인다. 작업을 독립적인 파일/모듈로 분리해서 맡겨라.
• 검토 부하 — 병렬로 돌린 만큼 검토할 diff도 배로 는다. 처리량이 곧 검토 능력을 넘으면 의미가 없다.

전체 운영 원칙 정리:

1. 컨텍스트를 정밀하게 — 넓게 던지지 말고 @로 조준. 규칙은 glob으로 필요할 때만.
2. 작업을 잘게 — 한 사이클 = 검토 가능한 분량 = 한 커밋.
3. 항상 검증 — AI의 완료 선언 ≠ 동작 확인. 빌드·테스트·실제 실행으로 확인.
4. 안전망 이중화 — 체크포인트(빠른 무르기) + git(영구 복구).
5. 보안 보수적으로 — 파괴적 명령 자동 실행 금지, 시크릿 커밋 금지, MCP 출처 검증.
6. 규칙 복리 — 반복 실수·반복 리뷰 지적을 규칙으로 축적.
7. 비용 = 정확도 — 컨텍스트 좁히기와 대화 짧게 유지는 비용과 품질을 동시에 개선.

마지막 함정 — 검토 없는 자동화의 유혹: Cursor가 강력해질수록 "그냥 다 맡기고 수락"하고 싶어진다. 하지만 프로덕션 코드에서 사람의 검토를 빼는 순간, 빠른 도구는 빠른 사고로 직결된다. Cursor는 당신을 대체하는 게 아니라 증폭한다 — 좋은 판단은 더 빠르게, 나쁜 판단도 더 빠르게. 검토와 검증이 그 차이를 가른다.

참고: Rules | Cursor Docs · Cursor 2026 가이드 | DeployHQ · .cursorrules vs MDC 2026