Cursor AI 에디터 완전 설치 가이드 - VS Code 마이그레이션부터 .cursorrules 설정까지 (2026)
Cursor AI 에디터란?
Cursor는 VS Code를 기반으로 만들어진 AI 네이티브 코드 에디터입니다. GPT-4, Claude 등 대형 언어 모델을 에디터에 직접 통합하여, 코드 작성·리팩토링·디버깅을 자연어 명령으로 수행할 수 있습니다. 기존 VS Code 사용자라면 확장 프로그램, 키바인딩, 테마를 그대로 가져올 수 있어 전환 비용이 거의 없습니다.
1단계: Cursor 설치
Windows
- 공식 사이트
https://cursor.com에 접속합니다.- Download for Windows 버튼을 클릭하여 설치 파일(CursorSetup.exe)을 다운로드합니다.- 설치 파일을 실행하고 안내에 따라 설치를 완료합니다.- 설치 후 Cursor를 실행하면 로그인 화면이 나타납니다. Google, GitHub, 또는 이메일로 가입합니다.
macOS
- 공식 사이트에서
.dmg파일을 다운로드합니다.- 다운로드된 파일을 열고 Cursor 아이콘을 Applications 폴더로 드래그합니다.- 터미널에서cursor명령어를 사용하려면 Cursor 내에서 Cmd+Shift+P →Install ‘cursor’ command을 실행합니다.
Linux
# AppImage 다운로드 후 실행 권한 부여
chmod +x cursor-.AppImage
./cursor-.AppImage
2단계: VS Code 설정 마이그레이션
Cursor는 VS Code 포크이므로 기존 설정을 원클릭으로 가져올 수 있습니다. - Cursor 최초 실행 시 **"Import from VS Code"** 옵션이 표시됩니다. 클릭합니다.- 마이그레이션 항목을 선택합니다:
settings.json 사용자 설정- **Keybindings** — 커스텀 키 바인딩- **Snippets** — 사용자 정의 스니펫# Cursor 내에서 Ctrl+Shift+P (Windows/Linux) 또는 Cmd+Shift+P (macOS)
# 명령어 입력:
Cursor: Import VS Code Settings수동으로 설정 파일을 복사하는 방법도 있습니다:
# Windows
copy %APPDATA%\Code\User\settings.json %APPDATA%\Cursor\User\settings.json
copy %APPDATA%\Code\User\keybindings.json %APPDATA%\Cursor\User\keybindings.json
macOS / Linux
cp ~/.config/Code/User/settings.json ~/.config/Cursor/User/settings.json
cp ~/.config/Code/User/keybindings.json ~/.config/Cursor/User/keybindings.json
3단계: AI 모델 및 API 설정
Cursor는 기본적으로 자체 AI 서비스를 제공하지만, 직접 API 키를 연결할 수도 있습니다.
- Ctrl+Shift+P → Cursor Settings을 엽니다.- **Models** 탭으로 이동합니다.- 사용할 모델을 선택합니다 (Claude Sonnet 4.6, GPT-4o 등).- 자체 API 키를 사용하려면 **OpenAI API Key** 필드에 키를 입력합니다:OpenAI API Key: sk-YOUR_API_KEY
Anthropic API Key: sk-ant-YOUR_API_KEY
## 4단계: .cursorrules로 프로젝트별 AI 규칙 설정
프로젝트 루트에 .cursorrules 파일을 생성하면, Cursor AI가 해당 프로젝트의 컨텍스트와 규칙을 자동으로 인식합니다.
기본 .cursorrules 예시
# .cursorrules
프로젝트 개요
이 프로젝트는 Next.js 14 기반의 SaaS 대시보드입니다.
기술 스택
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS v3
- State: Zustand
- Database: PostgreSQL + Prisma ORM
- Auth: NextAuth.js v5
코딩 규칙
- 모든 컴포넌트는 함수형 컴포넌트로 작성
- ‘use client’ 지시어는 꼭 필요한 경우에만 사용
- API 라우트는 app/api/ 디렉토리에 배치
- 에러 핸들링은 try-catch와 Error Boundary 활용
- 변수명과 함수명은 camelCase, 컴포넌트명은 PascalCase
금지 사항
- any 타입 사용 금지
- console.log를 프로덕션 코드에 남기지 않기
인라인 스타일 사용 금지
고급 .cursorrules 예시 (백엔드 프로젝트)
# .cursorrules
## 프로젝트: Python FastAPI 마이크로서비스
## 규칙
- Python 3.12+ 문법 사용
- 모든 함수에 타입 힌트 필수
- Pydantic v2 모델 사용
- 비동기 함수는 async/await 패턴 준수
- 테스트는 pytest + httpx AsyncClient 사용
- 환경 변수는 반드시 pydantic-settings로 관리
## 디렉토리 구조
app/
api/ # 라우터
models/ # Pydantic 모델
services/ # 비즈니스 로직
repositories/ # DB 접근 계층5단계: 핵심 AI 기능 활용
| 기능 | 단축키 | 설명 |
|---|---|---|
| AI Chat | Ctrl+L | 사이드바에서 AI와 대화하며 코드 질문 |
| Inline Edit | Ctrl+K | 선택한 코드를 자연어로 수정 지시 |
| Composer | Ctrl+I | 여러 파일에 걸친 대규모 변경 요청 |
| Tab Autocomplete | Tab | AI 기반 코드 자동 완성 |
| Codebase Search | @codebase | 전체 코드베이스를 컨텍스트로 활용 |
@파일명을 입력하면 해당 파일을 컨텍스트로 추가할 수 있습니다. @폴더명으로 전체 폴더도 가능합니다.- **.cursorignore 활용**: node_modules, dist, .env 등 AI가 참조하지 말아야 할 파일을 지정합니다. .gitignore와 동일한 문법을 사용합니다.- **Rules for AI 전역 설정**: Cursor Settings → General → Rules for AI에서 모든 프로젝트에 적용되는 전역 규칙을 설정할 수 있습니다.- **Notepads 기능**: 자주 사용하는 프롬프트를 Notepad에 저장하고 @notepad명으로 빠르게 호출합니다.- **모델 전환**: 간단한 작업에는 빠른 모델(GPT-4o-mini), 복잡한 작업에는 강력한 모델(Claude Opus)을 사용해 비용을 최적화하세요.
## Troubleshooting — 자주 발생하는 문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 확장 프로그램이 작동하지 않음 | VS Code 전용 확장과의 호환성 문제 | Cursor 마켓플레이스에서 동일 확장을 재설치하거나, Open VSX 레지스트리에서 호환 버전 확인 |
| AI 응답이 느리거나 타임아웃 | 네트워크 문제 또는 서버 과부하 | 모델을 변경하거나, Cursor Settings → Advanced → Timeout 값을 늘림 |
| 자동 완성이 동작하지 않음 | Tab Autocomplete 비활성화 상태 | Cursor Settings → Features → Copilot++에서 활성화 확인 |
| .cursorrules가 인식되지 않음 | 파일 위치 오류 | 반드시 프로젝트 **루트 디렉토리**에 위치해야 함. 파일명 오타 확인 |
| 메모리 사용량 과다 | 대형 프로젝트에서 인덱싱 부하 | .cursorignore에 불필요한 디렉토리 추가 |
Q1: Cursor는 무료인가요?
Cursor는 무료 플랜(Hobby)과 유료 플랜(Pro, Business)을 제공합니다. 무료 플랜에서는 월 2,000회의 자동 완성과 제한된 프리미엄 모델 요청이 가능합니다. Pro 플랜(월 $20)에서는 무제한 자동 완성과 500회의 빠른 프리미엄 요청이 제공됩니다.
Q2: VS Code 확장 프로그램과 100% 호환되나요?
Cursor는 VS Code 포크이므로 대부분의 확장 프로그램이 호환됩니다. 다만, 일부 Microsoft 전용 확장(예: Live Share, Remote SSH 일부 버전)은 라이선스 제한으로 직접 설치가 불가능할 수 있습니다. 이 경우 Open VSX 레지스트리의 대체 확장을 사용하세요.
Q3: .cursorrules와 .cursor/rules 디렉토리의 차이는 무엇인가요?
.cursorrules는 프로젝트 루트에 단일 파일로 배치하는 전통적인 방식입니다. 최신 버전에서는 .cursor/rules/ 디렉토리 안에 여러 규칙 파일을 분리하여 관리할 수 있습니다. 예를 들어 .cursor/rules/frontend.md, .cursor/rules/backend.md처럼 도메인별로 나누어 더 세밀한 규칙 적용이 가능합니다. 두 방식을 동시에 사용하면 .cursor/rules/가 우선 적용됩니다.