Cursor 셋업 — 설치부터 .cursorrules·MCP까지 + Claude Code와의 분담

Cursor는 VS Code 포크 + AI 통합 에디터. "코드 편집기 안에서 AI를 쓰는 표준 도구" 자리에서 가장 빠른 후보다. Claude Code와는 결이 다르다 — Cursor는 IDE 안의 페어 프로그래머, Claude Code는 터미널에서 일하는 에이전트. 둘은 충돌이 아니라 분담.

이 가이드는 macOS/Linux/Windows 공통으로 설치 → 핵심 사용 → .cursorrules → MCP → Claude Code와의 분담까지.

TL;DR

1. 설치: cursor.com → 자동 임포트(VS Code 확장·키맵·설정)
2. 모델 선택: Claude Sonnet/Opus·GPT-4.1·Cursor Composer. 기본은 Claude Sonnet 권장
3. 단축키 4개: Tab 자동완성 · ⌘K 인라인 편집 · ⌘L 사이드 채팅 · ⌘I Composer
4. .cursorrules: 프로젝트 룰 명시. Cursor가 모든 호출에 시스템 프롬프트로 자동 주입
5. Claude Code와 분담: Cursor = 편집·즉시 응답, Claude Code = 멀티 파일·자율 작업·CLI

사전 조건

• macOS 12+ / Windows 10+ / Linux (Ubuntu 22.04+)
• 인터넷 연결 + 계정 (Cursor 또는 GitHub OAuth)
• 기존 VS Code 사용자라면 import는 자동

1. 설치

macOS

brew install --cask cursor

Windows

winget install -e --id Anysphere.Cursor

Linux

cursor.com/downloads에서 AppImage 또는 .deb.

첫 실행 시 VS Code 설정(확장·키맵·테마)을 한 번에 임포트. 처음 쓰는 사람은 그냥 다음 다음.

2. 모델 선택

Cursor → Settings → Models. 권장:

• Claude Sonnet 4 — 일상적 편집·리팩토링. 빠름.
• Claude Opus 4 — 어려운 디버깅·아키텍처. 비싸지만 정확.
• Composer (Cursor 자체) — 멀티 파일 변경 + agentic. 베타 영역.
• GPT-4.1 / o1 — 백업/비교용.

Cursor 요금제(Pro)는 모델별 요청 한도가 있다. Sonnet은 한도가 크고 빠르므로 메인 모델로 두고, Opus는 막힐 때만.

3. 핵심 단축키 4종

Tab 자동완성

• 함수 시그니처 채움, 반복 패턴 완성, import 자동 삽입
• 신뢰 금지: 잘못된 API 호출·환각 잦음. Esc로 거부 자주 사용
• 옵션: Settings → Features → Cursor Tab → "Disable preview" 켜면 노이즈 ↓

⌘K 인라인 편집

// 선택: 함수 전체
// ⌘K: "에러 처리 추가하고 zod로 입력 검증"

선택 영역만 변경. 큰 작업 X. 의도 → 결과까지 가장 빠른 루프.

⌘L 사이드 채팅

• @파일이름 으로 파일을 컨텍스트에 첨부
• @Codebase 로 전체 코드베이스 검색 시도 (embedding 기반, 베타 품질)
• @Web 으로 최신 정보 (Cursor가 검색 수행)

⌘I Composer

여러 파일에 걸친 작업 ("auth flow 전체 리팩토링"). agentic 모드 활성화 시 파일 직접 수정. 결과를 한 번에 신뢰하지 말고 diff 단위로 수락/거부.

4. .cursorrules — 프로젝트 룰

프로젝트 루트의 .cursorrules 파일은 Cursor가 모든 채팅·편집·composer 호출에 시스템 프롬프트로 자동 주입. 코드 스타일·기술 스택·금지 항목을 명시해두면 매번 안내할 필요 없어진다.

4.1 템플릿 다운로드

Next.js + TypeScript 프로젝트용:

# Mac/Linux
curl -fsSL https://devalice.jaceclub.com/assets/ai-agents/cursor-setup/cursorrules-nextjs.txt -o .cursorrules
shasum -a 256 .cursorrules
# 기대값: 7f1ef76397375cae008ece09b46ddf91aa098dff5edaacebcd7e7e4dec92a21d

# Windows
Invoke-WebRequest -Uri https://devalice.jaceclub.com/assets/ai-agents/cursor-setup/cursorrules-nextjs.txt -OutFile .cursorrules

4.2 핵심 섹션 (템플릿에 포함)

• 프로젝트 컨텍스트 — 스택·패키지 매니저·언어 버전
• 코드 스타일 — strict TS·파일명 컨벤션·경로 별칭
• 라우팅/데이터 — App Router 패턴·ISR·env 분리
• 보안 — 시크릿 금지·입력 검증·SQL 바인딩
• 변경 범위 — 요청 밖 리팩토링 금지
• 출력 형식 — diff 형태·대안 1개 + 트레이드오프

4.3 효과

비교 (.cursorrules 없음 vs 있음):

❌ "여기 React 컴포넌트 만들어줘" → class component, JS, 임의 라이브러리 추가 ✅ "여기 React 컴포넌트 만들어줘" → strict TS Server Component, @/* 별칭, Tailwind 활용

룰 잘 짜면 매 호출의 첫 3-4줄 안내가 줄어든다.

5. .cursorignore

.gitignore와 같은 문법. AI가 컨텍스트로 가져가지 않을 파일 지정.

# 의존성·빌드
node_modules
.next
dist

# 거대 fixture
fixtures/large/

# 자동 생성 코드
src/generated/

이걸 안 하면 @Codebase 검색에 빌드 산출물이 잡혀 결과 품질 ↓.

6. MCP (Model Context Protocol)

Cursor 0.42+부터 MCP 서버 지원. 외부 도구(파일·DB·API)를 AI에 노출.

Settings → Features → MCP → Add Server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}

Claude Code와 동일한 MCP 표준. 같은 서버 정의를 양쪽에 공유 가능.

7. Privacy 모드

Settings → General → Privacy Mode:

• OFF (기본) — Cursor가 로그·요청을 모델 개선에 사용 가능
• ON — 학습 사용 안 함. 회사 코드 다룬다면 ON 강제

Privacy ON 시 일부 기능(코드 인덱싱)이 로컬만 사용. 성능 영향 미미.

8. Claude Code와의 분담

같이 쓰는 게 가장 강력하다. 역할 차이:

실전 분담 패턴

1. 짧은 편집 = Cursor ⌘K 한 함수 안에서 끝나는 변경. 즉시 결과 → 즉시 수락.

2. 멀티 파일 = Claude Code "라우트 4개에 ISR 추가" 같은 작업. CLI에서 한 번에 변경 + 빌드 검증.

3. 디버깅 = 둘 다 시도 Cursor에서 빠른 가설 → 안 되면 Claude Code로 깊이 있는 컨텍스트 + 자율 실행.

4. PR 생성 = Claude Code gh pr create 통합으로 끝까지 자동.

5. 리뷰 = Cursor ⌘L diff를 인라인으로 보고 한 줄씩 질문.

검증 방법

1. Cursor 열고 빈 index.tsx 파일에 Tab 자동완성 → 합리적 React 컴포넌트 시작 코드 제안
2. 함수 선택 → ⌘K로 "에러 처리 추가" → 에러 try/catch 추가
3. ⌘L 사이드 채팅에서 @package.json 첨부 → 의존성 질문
4. 프로젝트 루트에 .cursorrules 추가 후 새 채팅 → 룰이 반영되어 응답 달라지는지 확인
5. Settings → Privacy → ON → 정상 동작 유지 확인

트러블슈팅

Tab 자동완성이 너무 시끄럽다

Settings → Features → Cursor Tab → "Trigger more accurately" 또는 일시 disable. 자주 거부할 거면 끄는 게 효율적.

@Codebase 검색이 부정확

.cursorignore에 빌드 산출물·자동생성 코드 추가. Cursor에 codebase re-index 트리거 (Settings → Indexing).

Cursor 자체 모델이 자주 환각

모델을 Claude Sonnet로 강제. Settings → Models → Default Model = Claude Sonnet.

.cursorrules가 무시되는 느낌

• 파일 이름 정확 확인 (.cursorrules, 점 시작, 확장자 없음)
• 프로젝트 루트에 있어야 함 (서브폴더 X)
• 새 채팅에서 확인 (기존 채팅은 누적 컨텍스트로 인해 변화 적음)

Pro 한도 빠르게 소진

Composer를 너무 자주 호출 중. 짧은 편집은 ⌘K로, Composer는 진짜 멀티 파일 작업에만.

Claude Code와 키맵 충돌

Cursor는 IDE 안, Claude Code는 터미널. 충돌 자체는 거의 없지만 둘 다 ⌘L을 쓰는 경우 있음. Cursor 키맵 변경 권장.

참고

• Claude Code 셋업 — 터미널 에이전트 셋업이 함께 권장
• 멀티 에이전트 워크플로 — 여러 도구 같이 쓰는 패턴
• Cursor 공식 문서
• Cursor MCP 가이드

변경 이력

• 2026-05-12: 첫 작성. 설치·모델·단축키 4종·.cursorrules 템플릿·Claude Code 분담 5종 + 트러블슈팅 6종.