Cursor AI 코드 에디터 완벽 설치 가이드 - VS Code 마이그레이션부터 .cursorrules 설정까지
Cursor AI 코드 에디터란?
Cursor는 VS Code를 기반으로 만들어진 AI 네이티브 코드 에디터입니다. GPT-4, Claude 등 최신 AI 모델을 코드 작성 워크플로우에 직접 통합하여, 코드 자동 완성·리팩토링·디버깅을 획기적으로 가속합니다. 기존 VS Code 사용자라면 확장 프로그램과 설정을 그대로 가져올 수 있어 전환 비용이 거의 없습니다.
1단계: Cursor 다운로드 및 설치
- 공식 사이트 접속 —
https://cursor.com에서 운영체제(Windows, macOS, Linux)에 맞는 설치 파일을 다운로드합니다.- Windows 설치 — 다운로드된CursorSetup.exe를 실행합니다. 설치 마법사의 안내에 따라 진행하세요.# Windows (winget 사용 시) winget install Anysphere.Cursor- macOS 설치
- Linux 설치 — 공식 사이트에서# Homebrew 사용 시 brew install —cask cursor.AppImage파일을 다운로드한 뒤 실행 권한을 부여합니다.
- 첫 실행 — Cursor를 처음 열면 계정 생성 또는 로그인 화면이 나타납니다. GitHub 계정으로 간편하게 가입할 수 있습니다.chmod +x cursor-.AppImage ./cursor-.AppImage
2단계: VS Code 설정 마이그레이션
Cursor는 첫 실행 시 자동으로 VS Code 마이그레이션을 제안합니다. 수동으로 진행하려면 아래 단계를 따르세요.
- **자동 마이그레이션** — 첫 실행 시 *"Import VS Code Settings"* 옵션을 선택하면 확장 프로그램, 키바인딩, 테마, 사용자 설정이 모두 복사됩니다.- **수동 설정 복사** — 자동 마이그레이션을 놓쳤을 경우, Ctrl+Shift+P(macOS: Cmd+Shift+P)로 명령 팔레트를 열고 Cursor: Import VS Code Settings를 검색하여 실행합니다.- **확장 프로그램 확인** — 마이그레이션 후 사이드바의 확장 프로그램 탭에서 기존 확장이 정상 설치되었는지 확인합니다.
### settings.json 직접 복사
# VS Code settings.json 위치
# Windows: %APPDATA%\Code\User\settings.json
# macOS: ~/Library/Application Support/Code/User/settings.json
# Linux: ~/.config/Code/User/settings.json
Cursor settings.json 위치
Windows: %APPDATA%\Cursor\User\settings.json
macOS: ~/Library/Application Support/Cursor/User/settings.json
Linux: ~/.config/Cursor/User/settings.json
수동 복사 (macOS/Linux 예시)
cp ~/Library/Application\ Support/Code/User/settings.json
~/Library/Application\ Support/Cursor/User/settings.json
3단계: AI 모델 선택 및 구성
Cursor는 여러 AI 모델을 지원합니다. Cursor Settings → Models에서 설정할 수 있습니다.
| 모델 | 특징 | 추천 용도 |
|---|---|---|
| GPT-4o | 빠른 응답, 범용 코딩 | 일반 코드 작성·자동 완성 |
| Claude Sonnet 4.6 | 정밀한 코드 분석, 긴 컨텍스트 | 대규모 리팩토링·코드 리뷰 |
| Claude Opus 4.6 | 최고 수준 추론 능력 | 복잡한 아키텍처 설계·디버깅 |
| cursor-small | 경량 모델, 빠른 Tab 완성 | 코드 자동 완성(Tab) |
Cursor Settings → Models → OpenAI API Key에 입력합니다.
// Cursor Settings에서 직접 입력하거나,
// 환경 변수로 설정
export OPENAI_API_KEY="YOUR_API_KEY"
export ANTHROPIC_API_KEY="YOUR_API_KEY"
## 4단계: .cursorrules 프로젝트 설정
.cursorrules 파일은 프로젝트 루트에 배치하여 AI에게 프로젝트별 컨텍스트와 규칙을 전달하는 설정 파일입니다.
# 프로젝트 루트에 .cursorrules 파일 생성
touch .cursorrules
### .cursorrules 예시
# .cursorrules
You are an expert in TypeScript, React 19, and Next.js 15 App Router.
Project Context
- This is a SaaS dashboard application
- We use Tailwind CSS v4 for styling
- State management: Zustand
- Database: PostgreSQL with Drizzle ORM
- Authentication: NextAuth.js v5
Code Style Rules
- Use functional components with arrow functions
- Prefer named exports over default exports
- Use TypeScript strict mode — no
any types
- Write Korean comments for business logic
- All API routes must include error handling with proper HTTP status codes
File Structure
- Components: src/components/{feature}/{ComponentName}.tsx
- API Routes: src/app/api/{resource}/route.ts
- Utilities: src/lib/{utilName}.ts
Testing
- Use Vitest for unit tests
- Test files: tests/{ComponentName}.test.tsx
Minimum coverage: 80%
5단계: 핵심 워크플로우 활용
인라인 편집 (Ctrl+K)
코드를 선택한 뒤 Ctrl+K(macOS: Cmd+K)를 누르고 자연어로 수정 요청을 입력하세요.
// 선택 후 Ctrl+K → "이 함수를 async/await 패턴으로 변환해줘"
function fetchData() {
return fetch('/api/data').then(res => res.json());
}
// AI 변환 결과
async function fetchData() {
const res = await fetch(‘/api/data’);
return res.json();
}
AI 채팅 (Ctrl+L)
Ctrl+L로 사이드 채팅 패널을 열고 코드베이스 전체에 대한 질문이나 작업을 요청할 수 있습니다. @파일명으로 특정 파일을 참조하거나, @Codebase로 전체 프로젝트를 컨텍스트에 포함시킵니다.
Agent 모드 (Ctrl+I)
Composer의 Agent 모드를 사용하면 여러 파일을 동시에 생성·수정하는 복잡한 작업을 자동으로 수행합니다. 터미널 명령 실행까지 AI가 직접 처리합니다.
Pro Tips — 파워 유저를 위한 고급 활용법
- .cursorignore 활용 —
node_modules,dist,.env등 AI가 읽을 필요 없는 파일을 제외하여 컨텍스트 품질을 높이세요.# .cursorignore node_modules/ dist/ .env* *.lock- @Web 명령어 — 채팅에서@Web을 입력하면 최신 문서나 라이브러리 정보를 실시간 검색하여 답변에 반영합니다.- @Docs 커스텀 문서 등록 —Cursor Settings → Features → Docs에서 자주 참조하는 라이브러리 문서 URL을 등록해 두면@Docs로 즉시 참조할 수 있습니다.- 키보드 단축키 커스텀 —Ctrl+Shift+P → Preferences: Open Keyboard Shortcuts (JSON)에서 AI 관련 단축키를 자신의 워크플로우에 맞게 변경하세요.- Privacy Mode 활성화 —Cursor Settings → General → Privacy Mode를 켜면 코드가 Cursor 서버에 저장되지 않습니다. 기업 보안 정책이 엄격한 환경에 필수입니다.
Troubleshooting — 자주 발생하는 문제 해결
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| AI 응답이 매우 느림 | 모델 서버 과부하 또는 네트워크 문제 | 모델을 cursor-small로 변경하거나, VPN 사용 시 해제 후 재시도 |
| VS Code 확장이 작동하지 않음 | 호환되지 않는 확장 버전 | 확장을 삭제 후 Cursor 마켓플레이스에서 재설치 |
| 자동 완성(Tab)이 작동 안 함 | 설정에서 Copilot++ 비활성화 | Cursor Settings → Features → Copilot++ 활성화 확인 |
.cursorrules가 무시됨 | 파일이 프로젝트 루트가 아닌 곳에 위치 | 파일을 프로젝트 최상위 디렉토리로 이동 |
| "Rate limit exceeded" 오류 | 무료 플랜 요청 한도 초과 | Pro 플랜으로 업그레이드하거나 자체 API 키 사용 |
Q1: Cursor는 무료로 사용할 수 있나요?
네, Cursor는 무료 플랜(Hobby)을 제공합니다. 월 2,000회의 코드 자동 완성과 제한된 횟수의 프리미엄 모델 요청을 사용할 수 있습니다. 더 많은 요청과 고급 기능이 필요하면 Pro 플랜(월 $20)이나 Business 플랜(월 $40/사용자)을 선택할 수 있습니다.
Q2: 기존 VS Code로 돌아갈 수 있나요?
물론입니다. Cursor는 VS Code와 완전히 독립적으로 설치되므로 기존 VS Code가 삭제되지 않습니다. 두 에디터를 동시에 사용할 수 있으며, Cursor 사용을 중단하더라도 VS Code 환경에는 영향이 없습니다. 설정 파일도 별도 경로에 저장됩니다.
Q3: .cursorrules와 .cursor/rules 디렉토리의 차이는 무엇인가요?
.cursorrules는 프로젝트 루트에 단일 파일로 배치하는 레거시 방식입니다. 최신 Cursor 버전에서는 .cursor/rules/ 디렉토리 안에 여러 규칙 파일을 분리하여 관리할 수 있습니다. 예를 들어 .cursor/rules/frontend.md, .cursor/rules/backend.md처럼 도메인별로 분리하면 더 체계적인 관리가 가능합니다. 두 방식 모두 지원되지만, 새로운 프로젝트에서는 디렉토리 방식을 권장합니다.