Cursor 가이드

소개

Cursor는 VS Code를 포크하여 AI 기능을 네이티브로 통합한 코드 에디터입니다. GitHub Copilot이나 Continue보다 한 단계 더 깊은 AI 통합을 제공하며, GPT-5.4, Claude(claude-opus-4-7, claude-sonnet-4-6), Gemini 3.1 Pro 등 최신 모델을 동시에 지원합니다. 2026년 4월 기준 공식 페이지에서는 Cloud Agents, Bugbot, MCPs, skills, hooks를 핵심 기능군으로 안내합니다.

왜 Cursor인가?

핵심 기능

• Cmd+K (AI Edit): 코드 블록 인라인 편집
• Cmd+L (Chat): AI와 대화하며 코딩
• Tab (Autocomplete): 코드 자동완성
• Composer: 여러 파일 동시 생성/수정
• @-mentions: 파일, 폴더, 문서, 웹 참조
• Terminal Cmd+K: 터미널 명령어 생성
• Plan Mode: 복잡한 작업을 단계별로 분해하는 스마트 계획 모드
• Arena Mode: 두 모델을 나란히 비교하여 블라인드 투표로 최적 모델 선택
• Bugbot Autofix: PR 자동 리뷰 및 클라우드 에이전트 기반 수정 제안

설치

다운로드 및 설치

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: 무료
- Pro: $20/월
- Pro+: $60/월
- Ultra: $200/월

# 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로 실행

Plan Mode (작업 계획)

복잡한 작업을 수행하기 전에 AI가 먼저 단계별 계획을 수립합니다. 코드 변경 전에 어떤 파일을 어떻게 수정할지 미리 검토할 수 있어, 대규모 리팩토링이나 기능 구현에서 예측 가능성이 크게 높아집니다.

# Plan Mode 활성화
채팅 또는 Composer에서 "Plan" 토글 ON

💬 You: "인증 시스템을 JWT에서 세션 기반으로 전환해줘"

🤖 Cursor (Plan):
# AI가 먼저 계획 제시:
1. middleware.ts — JWT 검증 → 세션 검증 로직 변경
2. lib/auth.ts — 세션 스토어 설정 추가
3. api/login/route.ts — 세션 생성 로직
4. api/logout/route.ts — 세션 파기 로직
5. types/session.d.ts — 세션 타입 정의

# 계획 승인 후 실행

Arena Mode (모델 비교)

동일한 프롬프트에 대해 두 모델의 응답을 나란히 비교합니다. 모델 이름이 숨겨진 상태에서 결과를 평가하고 투표하여, 프로젝트에 가장 적합한 모델을 객관적으로 선택할 수 있습니다.

# Arena Mode 사용
Settings → Cursor Settings → Arena Mode: ON

# 두 모델의 응답이 나란히 표시됨
┌─────────────────┬─────────────────┐
│   Model A       │   Model B       │
│   (숨겨진 이름)   │   (숨겨진 이름)   │
├─────────────────┼─────────────────┤
│   응답 내용 A    │   응답 내용 B    │
└─────────────────┴─────────────────┘

# 더 나은 응답에 투표 → 모델 이름 공개

Bugbot Autofix (PR 자동 리뷰)

GitHub PR이 생성되면 Bugbot이 자동으로 코드를 리뷰하고, 클라우드 에이전트를 띄워 테스트를 실행한 뒤 수정안을 제안합니다. CI/CD 파이프라인에 통합하여 코드 품질을 자동으로 관리할 수 있습니다.

# Bugbot Autofix 워크플로우
1. 개발자가 PR 생성
2. Bugbot이 자동으로 변경사항 분석
3. 클라우드 샌드박스에서 빌드/테스트 실행
4. 발견된 이슈에 대한 수정 코드 제안
5. 개발자가 제안 검토 후 수락/거부

# Settings → Cursor Settings → Bugbot
- Auto-review: ON
- Test command: npm test
- Lint command: npm run lint

Cloud Agents (클라우드 에이전트)

자체 네트워크 내에서 호스팅되는 클라우드 에이전트입니다. 코드와 도구 실행이 조직의 인프라에서 이루어지므로, 보안에 민감한 엔터프라이즈 환경에서도 안심하고 사용할 수 있습니다.

# Cloud Agent 특징
- 코드가 조직 네트워크를 벗어나지 않음
- 자체 인프라에서 도구 실행 (빌드, 테스트 등)
- 팀 전용 환경 설정 가능
- VPN/프라이빗 네트워크 내에서 동작

# 설정 (Team/Enterprise 플랜)
Settings → Cursor Settings → Cloud Agents
→ Self-hosted endpoint 지정

Cursor Automations (자동화)

일정이나 이벤트에 따라 자동으로 에이전트가 실행됩니다. 클라우드 샌드박스에서 작업이 수행되며, 코드 포매팅, 의존성 업데이트, 테스트 실행 등 반복 작업을 자동화할 수 있습니다.

# Automations 예시

# 1. 스케줄 기반: 매일 오전 9시 의존성 체크
트리거: cron (0 9 * * *)
작업: "npm audit 실행 후 취약점 보고서 생성"

# 2. 이벤트 기반: PR 생성 시 자동 테스트
트리거: pull_request.opened
작업: "전체 테스트 실행 및 커버리지 보고"

# 3. 이벤트 기반: 이슈 할당 시 초안 작성
트리거: issue.assigned
작업: "이슈 분석 후 구현 초안 PR 생성"

향상된 코드 검색

로컬 텍스트 인덱스를 사용하여 대규모 저장소에서도 빠른 코드 검색이 가능합니다. 프로젝트 전체를 즉시 인덱싱하여 @Codebase 멘션의 정확도와 응답 속도가 크게 향상되었습니다.

# 향상된 코드 검색 특징
- 로컬 텍스트 인덱스로 대규모 모노레포 지원
- 수만 개 파일에서도 밀리초 단위 검색
- 심볼, 타입, 함수 시그니처 기반 시맨틱 검색
- @Codebase 멘션 시 관련 코드 정확도 향상

# 인덱싱 상태 확인
우측 하단 상태바 → "Indexing: Complete"

JetBrains IDE 지원

Cursor는 공식 문서에서 JetBrains 계열 지원도 함께 안내합니다. 다만 IDE별 지원 범위와 설정 흐름은 빠르게 바뀌므로, 실제 도입 전에는 현재 공식 설치 문서를 함께 확인하세요.

# JetBrains에서 Cursor 사용

# 1. 플러그인 설치
JetBrains IDE → Settings → Plugins
→ "Cursor" 검색 → Install

# 2. 계정 연동
Settings → Cursor → Sign In
→ 기존 Cursor 계정으로 로그인

# 3. 지원 IDE 목록
- IntelliJ IDEA (Java, Kotlin)
- PyCharm (Python)
- WebStorm (JavaScript, TypeScript)
- GoLand (Go)
- CLion (C/C++)
- Rider (.NET)

# 4. 사용 가능 기능
- AI 채팅 (Cmd+L)
- 인라인 편집 (Cmd+K)
- 자동완성 (Tab)
- @-mentions

설정

모델 선택

# Settings → Cursor Settings → Models

# 채팅용 모델
- GPT-5.4 (가장 강력, GPT-4o 후속)
- GPT-5.4 mini (빠르고 저렴)
- claude-sonnet-4-6 (균형, 코드 품질 우수)
- claude-opus-4-7 (최고 품질)
- Gemini 3.1 Pro (Google)

# 자동완성용 모델
- cursor-small (빠름, 기본)
- GPT-5.4 mini (더 정확)

Rules (.cursor/rules)

현재 Cursor는 프로젝트 루트의 .cursor/rules/ 디렉토리에서 프로젝트별 AI 지시사항을 관리합니다.

# .cursor/rules/project.mdc

# 프로젝트 지시사항

## 기술 스택
- 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. .cursor/rules/ 작성
# 프로젝트 규칙 정의

# 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-5.4, Claude, Gemini 3.1 Pro를 모두 사용하고 싶음
• 프로젝트별 규칙 설정이 필요함 (.cursor/rules/)
• Pro 이상 구독 비용이 부담되지 않음
• 전문적인 개발 환경 구축

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

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

가격 및 플랜

비용 비교

팁과 트릭

생산성 팁

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

필수 단축키

모범 사례

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

운영 플레이북

Cursor는 IDE 통합도가 높아 빠르지만, 팀 운영에서는 모델 사용 기준과 승인 경계를 먼저 정해야 품질이 안정됩니다. 아래 기준은 팀 공통 운영 템플릿으로 바로 사용할 수 있습니다.

요청 템플릿 표준

# Cursor 요청 템플릿 (권장)
목표: 무엇을 바꿀지 1문장
범위: 수정 허용 파일/디렉토리
제약: 금지 파일, 성능/보안 제약
검증: 테스트/빌드/리뷰 기준
출력: 변경 요약 + 리스크 3개

모델 정책 매트릭스

비용 관리 기준

• 개인 월 예산과 팀 월 예산을 별도로 지정
• 자동완성은 고정 저비용 모델 우선
• 긴 컨텍스트 작업은 요청 전 범위 축소 후 실행
• 주간 리포트: 요청 수, 재시도 수, 상위 모델 사용 비율

트러블슈팅

일반적인 문제

❌ Composer가 작동하지 않음

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

해결:

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

❌ 자동완성이 느림

해결:

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

❌ API 한도 초과

해결:

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

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

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

해결:

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

핵심 정리

• Cursor는 VS Code 포크 기반의 AI 네이티브 IDE로, GPT-5.4, Claude(claude-opus-4-7, claude-sonnet-4-6), Gemini 3.1 Pro 등 최신 모델을 지원합니다.
• Cmd+K(인라인 편집), Cmd+L(채팅), Composer(멀티파일), Tab(자동완성)이 핵심 기능이며, Plan Mode와 Arena Mode로 작업 품질을 높일 수 있습니다.
• Bugbot, Cloud Agents, MCPs, skills, hooks가 최신 기능군의 중심이며, 반복 작업과 장기 실행 워크플로우에 강합니다.
• 프로젝트 규칙은 .cursor/rules/ 디렉토리 기준으로 정리하는 것이 현재 흐름입니다.
• 로컬 텍스트 인덱스 기반 향상된 코드 검색으로 대규모 저장소에서도 빠른 컨텍스트 제공이 가능합니다.