Cursor IDE 가이드

소개

Cursor는 VS Code를 포크하여 AI 기능을 네이티브로 통합한 코드 에디터입니다. GitHub Copilot이나 Continue보다 한 단계 더 깊은 AI 통합을 제공하며, GPT-4와 Claude를 동시에 지원합니다.

왜 Cursor인가?

핵심 기능

• Cmd+K (AI Edit): 코드 블록 인라인 편집
• Cmd+L (Chat): AI와 대화하며 코딩
• Tab (Autocomplete): 코드 자동완성
• Composer: 여러 파일 동시 생성/수정
• @-mentions: 파일, 폴더, 문서, 웹 참조
• Terminal Cmd+K: 터미널 명령어 생성

설치

다운로드 및 설치

macOS

# 공식 웹사이트에서 다운로드
https://cursor.sh

# 또는 Homebrew
brew install --cask cursor

Windows

# 공식 웹사이트에서 다운로드
https://cursor.sh

# 실행 파일 다운로드 및 설치

Linux

# AppImage 다운로드
https://cursor.sh

# 실행 권한 부여
chmod +x cursor*.AppImage
./cursor*.AppImage

VS Code에서 마이그레이션

Cursor는 VS Code 포크이므로 기존 설정, 확장, 테마를 모두 가져올 수 있습니다.

# Cursor 첫 실행 시
1. "Import VS Code Settings" 선택
2. 확장, 테마, 키 바인딩, 스니펫 모두 자동 가져오기
3. 즉시 사용 가능

# 또는 수동 가져오기
Settings (Cmd+,) → Cursor Settings → Import from VS Code

초기 설정

# 1. 계정 생성 (무료)
Cursor 실행 → "Sign Up" → 이메일 입력

# 2. 플랜 선택
- Free: 월 2000회 요청 (GPT-4 500회, GPT-3.5 2000회)
- Pro: 변동/월 (무제한 GPT-4, Claude 포함)

# 3. 단축키 익히기
Cmd/Ctrl + K      # AI 편집
Cmd/Ctrl + L      # 채팅

주요 기능

Cmd+K (AI Edit)

코드 블록을 선택하고 Cmd+K를 누르면 AI가 즉시 편집합니다. Cursor의 가장 핵심적인 기능입니다.

사용 예시

// 1. 코드 생성
// 빈 줄에 Cmd+K

[Cursor]: "사용자 로그인 함수 만들어줘. async/await 사용."

// AI가 생성:
async function loginUser(email, password) {
  try {
    const response = await fetch('/api/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password })
    });
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Login failed:', error);
    throw error;
  }
}

// 2. 코드 수정
// 기존 코드 선택 후 Cmd+K

function sum(arr) {
  let total = 0;
  for (let i = 0; i < arr.length; i++) {
    total += arr[i];
  }
  return total;
}

[Cursor]: "reduce로 리팩토링해줘"

// AI가 변환:
const sum = (arr) => arr.reduce((acc, val) => acc + val, 0);

// 3. 버그 수정
// 에러 나는 코드 선택 후 Cmd+K

[Cursor]: "이 코드에서 TypeError 발생해. 수정해줘."

// AI가 자동으로 null 체크 추가

Cmd+L (Chat)

사이드바에서 AI와 대화하며 코드를 작성합니다. 복잡한 요구사항이나 질문에 적합합니다.

# 채팅 패널 열기
Cmd/Ctrl + L

💬 You: "Next.js 13 앱에 인증 시스템 추가해줘.
- NextAuth.js 사용
- Google OAuth
- JWT 세션
- 미들웨어로 보호된 라우트

필요한 파일 모두 생성해줘."

🤖 Cursor: "NextAuth.js 인증 시스템을 구성하겠습니다..."

# 여러 파일이 자동 생성됨
- app/api/auth/[...nextauth]/route.ts
- middleware.ts
- lib/auth.ts
- .env.example

채팅 @-mentions

💬 You: "@Files:src/App.tsx 이 컴포넌트에 라우팅 추가해줘.
@Docs React Router 최신 버전 사용."

🤖 Cursor: "React Router v6 문서를 참조했습니다.
App.tsx를 수정하겠습니다..."

Composer (멀티파일 편집)

Cursor의 킬러 기능. 여러 파일을 동시에 생성하고 수정하는 강력한 도구입니다.

# Composer 열기
Cmd/Ctrl + Shift + L

💬 You: "블로그 기능 전체 구현해줘.

필요한 것:
- 데이터베이스 스키마 (Prisma)
- API 라우트 (CRUD)
- UI 컴포넌트 (목록, 상세, 작성)
- 타입 정의 (TypeScript)

Next.js 13 App Router, TypeScript, Prisma, Tailwind 사용."

🤖 Cursor Composer: "블로그 시스템을 생성하겠습니다..."

# AI가 자동으로 여러 파일 생성/수정
- prisma/schema.prisma
- app/api/posts/route.ts
- app/api/posts/[id]/route.ts
- app/blog/page.tsx
- app/blog/[slug]/page.tsx
- components/PostCard.tsx
- components/PostForm.tsx
- types/post.ts
- lib/prisma.ts

Composer 장점

• 멀티파일: 10개 이상 파일도 한 번에 처리
• 일관성: 파일 간 일관된 코드 스타일 유지
• 의존성: 파일 간 의존성 자동 처리
• 검토: 변경사항을 미리 보고 수락/거부

Tab (Autocomplete)

GitHub Copilot처럼 코드를 타이핑하면 자동으로 완성 제안이 나타납니다.

// 타이핑 중...
const fetchUsers = async () =>

// Cursor가 자동 제안 (회색 텍스트):
const fetchUsers = async () => {
  const response = await fetch('/api/users');
  const data = await response.json();
  return data;
};

// Tab 키로 수락

Terminal Cmd+K

터미널에서도 Cmd+K를 사용하여 명령어를 생성할 수 있습니다.

# 터미널에서 Cmd+K
[Cursor]: "Git에서 최근 5개 커밋 보기"

# AI가 생성:
git log -5 --oneline

# Enter로 실행

설정

모델 선택

# Settings → Cursor Settings → Models

# 채팅용 모델
- GPT-4 (가장 강력)
- GPT-3.5-turbo (빠르고 저렴)
- Claude Sonnet (균형) (코드 품질 우수)
- Claude Opus (고성능) (최고 품질)
- Gemini Pro (Google)

# 자동완성용 모델
- cursor-small (빠름, 기본)
- gpt-3.5-turbo (더 정확)

Rules (.cursorrules)

프로젝트 루트에 .cursorrules 파일을 생성하여 프로젝트별 AI 지시사항을 설정할 수 있습니다.

# .cursorrules

# 프로젝트 지시사항

## 기술 스택
- TypeScript (strict mode)
- Next.js 13+ (App Router)
- Tailwind CSS
- Prisma ORM
- Jest + React Testing Library

## 코드 스타일
- 함수형 컴포넌트 (React Hooks)
- async/await (Promise 대신)
- ESLint + Prettier 준수
- 모든 함수에 JSDoc 주석

## 네이밍 규칙
- 컴포넌트: PascalCase (UserProfile)
- 함수: camelCase (getUserData)
- 상수: UPPER_SNAKE_CASE (API_BASE_URL)
- 파일명: kebab-case (user-profile.tsx)

## 테스트
- 모든 유틸 함수는 테스트 필수
- 최소 80% 코드 커버리지 유지
- E2E 테스트는 중요 플로우만

## 에러 처리
- try-catch 필수
- 사용자 친화적 에러 메시지
- 에러 로깅 (console.error)

## 보안
- 환경 변수로 비밀 관리 (.env)
- SQL injection 방지 (Prisma 사용)
- XSS 방지 (입력 검증)

## 성능
- 이미지 최적화 (Next.js Image)
- 코드 분할 (dynamic import)
- 불필요한 리렌더링 방지 (React.memo)

이제 모든 AI 응답이 이 규칙을 따릅니다.

프라이버시 모드

# Settings → Cursor Settings → Privacy Mode

- Privacy Mode: ON
  → 코드가 서버로 전송되지 않음
  → 단, 일부 기능 제한 (Codebase 검색 등)

- Privacy Mode: OFF (기본)
  → 전체 기능 사용
  → 코드는 암호화되어 전송, 저장되지 않음

실전 워크플로우

새 프로젝트 시작

# 1. Composer로 프로젝트 구조 생성
Cmd+Shift+L

💬 You: "Next.js 14 블로그 프로젝트 생성해줘.

구조:
- TypeScript
- App Router
- Tailwind CSS
- Prisma (PostgreSQL)
- NextAuth.js (Google OAuth)
- ESLint + Prettier

필요한 모든 설정 파일과 초기 구조 만들어줘."

# 2. .cursorrules 작성
# 프로젝트 규칙 정의

# 3. 본격 개발
# Cmd+K로 코드 작성

기능 개발

# 시나리오: 댓글 기능 추가

# 1. Composer로 전체 구조
Cmd+Shift+L

💬 You: "블로그 글에 댓글 기능 추가해줘.
- Prisma 스키마 업데이트
- API 라우트 (CRUD)
- 댓글 컴포넌트
- 최적화 (낙관적 업데이트)"

# 2. 개별 파일 세부 조정
# Cmd+K로 미세 조정

# 3. 테스트
💬 You: "@Files:lib/comments.ts 이 파일 테스트 작성해줘"

리팩토링

# 코드 선택 후 Cmd+K
[Cursor]: "이 코드를 다음과 같이 개선해줘:
- TypeScript strict 모드 호환
- 에러 처리 추가
- 성능 최적화 (메모이제이션)
- JSDoc 주석 작성"

디버깅

# 1. 터미널 에러 복사
TypeError: Cannot read property 'map' of undefined
  at UserList.render (UserList.tsx:25:18)

# 2. 채팅에 붙여넣기
💬 You: "@Files:components/UserList.tsx

이 에러 수정해줘:
[에러 로그 붙여넣기]"

🤖 Cursor: "UserList.tsx를 확인했습니다.
users prop이 undefined일 때 발생하는 에러입니다.
Optional chaining을 추가하겠습니다."

# 파일이 자동으로 수정됨

다른 도구와 비교

vs VS Code + GitHub Copilot

vs Continue

vs Codex

Cursor는 IDE 중심의 통합 환경이고, Codex는 앱/웹/CLI에서 작업 단위로 실행되는 코딩 에이전트입니다. 에이전트 분리 실행이 필요하면 Codex 가이드를 참고하세요.

Cursor를 선택해야 하는 경우

• 최고 품질의 AI 코딩 경험을 원함
• 멀티파일 편집이 자주 필요함 (Composer)
• GPT-4와 Claude를 모두 사용하고 싶음
• 프로젝트별 규칙 설정이 필요함 (.cursorrules)
• 변동/월 비용이 부담되지 않음
• 전문적인 개발 환경 구축

Cursor를 선택하지 말아야 하는 경우

• 완전 무료 솔루션 필요 → Continue + Ollama
• 기존 VS Code 환경 유지 → Continue 확장
• 오픈소스 도구 선호 → Continue
• 로컬 LLM 사용 필수 → Continue + Ollama
• 자율 에이전트 필요 → Cline

가격 및 플랜

Free 플랜

Pro 플랜 (변동/월)

비용 비교

팁과 트릭

생산성 팁

1. Cmd+K 우선: 간단한 수정은 Cmd+K (빠름)
2. Composer 활용: 복잡한 기능은 Composer (강력)
3. @-mentions: 정확한 컨텍스트 제공
4. .cursorrules: 프로젝트 규칙 명확히
5. 모델 전환: 작업에 맞는 모델 선택

필수 단축키

모범 사례

• 명확한 요청: "React 컴포넌트" → "React + TypeScript + Tailwind 컴포넌트"
• 컨텍스트 제공: @Files, @Docs로 참조 명확히
• 단계별 접근: 복잡한 작업은 단계별로 분할
• 검토 필수: AI 생성 코드 항상 검토
• 반복 개선: 첫 결과가 부족하면 추가 요청

트러블슈팅

일반적인 문제

❌ Composer가 작동하지 않음

원인: 워크스페이스 미설정 또는 인덱싱 미완료

해결:

1. 폴더 열기 (File → Open Folder)
2. 코드베이스 인덱싱 대기 (우측 하단 상태바 확인)
3. Composer 재시도

❌ 자동완성이 느림

해결:

Settings → Cursor Settings → Models
→ Autocomplete Model: cursor-small (더 빠름)

❌ API 한도 초과

해결:

• Free 플랜: 다음 달까지 대기 또는 Pro 업그레이드
• Pro 플랜: 더 가벼운 모델 사용 (GPT-3.5)

❌ VS Code 확장이 작동하지 않음

원인: 일부 VS Code 확장과 충돌

해결:

1. 확장 비활성화 후 재시도
2. Cursor 재시작
3. 확장 하나씩 활성화하며 테스트

핵심 정리

• Cursor IDE 가이드의 핵심 개념과 흐름을 정리합니다.
• 소개를 단계별로 이해합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.