# Cursor 에디터 설정 가이드 (Nuxt 4 최적화)

> 작성일: 2026-03-19
> 버전: v1.0
> 담당: 시니어 Dev
> 적용 대상: FE 팀 전원

---

## 개요

Cursor는 AI 기반 코드 에디터로, VS Code 기반 위에 Claude/GPT-4 등 LLM을 통합하여
코드 생성·리팩토링·디버깅을 대화형으로 지원합니다.
이 가이드는 Nuxt 4 프로젝트에 최적화된 Cursor 설치 및 설정 방법을 안내합니다.

### GitHub Copilot과의 차이점

| 항목 | GitHub Copilot | Cursor |
|------|---------------|--------|
| 기반 에디터 | VS Code (플러그인) | VS Code 포크 (독립 에디터) |
| AI 엔진 | GitHub (OpenAI 기반) | Claude / GPT-4o / 자체 모델 선택 가능 |
| 컨텍스트 | 현재 파일 중심 | 프로젝트 전체 인덱싱 (@codebase) |
| 대화형 편집 | 제한적 (인라인 제안) | Composer: 멀티파일 동시 편집 |
| 프로젝트 규칙 | 없음 | `.cursorrules` / `.cursor/rules/` |
| 가격 | $19/월 (Business) | $20/월 (Pro), 무료 티어 있음 |

> **권장**: Cursor를 주 에디터로 사용하고, Copilot은 VS Code 환경에서 병행 사용

---

## 1. 설치

### 1-1. 다운로드 및 설치

1. [cursor.com](https://www.cursor.com) 접속
2. **Download for Mac** 클릭 (macOS 기준)
3. `.dmg` 파일 실행 → Applications 폴더로 드래그

### 1-2. 기존 VS Code 설정 가져오기

최초 실행 시 **"Import from VS Code"** 선택:
- 익스텐션, 키바인딩, 테마, 설정이 자동으로 이전됩니다.
- 기존 VS Code 사용자는 적응 비용 최소화

### 1-3. 계정 연동

1. Cursor 실행 → 우측 하단 프로필 아이콘 클릭
2. **Sign In** → GitHub 계정으로 로그인 (권장)
3. 팀 플랜 사용 시 초대 링크로 팀 워크스페이스 참여

---

## 2. 초기 설정

### 2-1. AI 모델 선택

`Cursor Settings` (⌘ + ,) → **Models** 탭:

| 모델 | 추천 용도 | 속도 |
|------|----------|------|
| `claude-sonnet-4-6` | 복잡한 리팩토링, 아키텍처 설계 | 중간 |
| `claude-haiku-4-5` | 빠른 자동완성, 간단한 수정 | 빠름 |
| `gpt-4o` | 대안 모델 | 중간 |

> **권장**: 기본 모델을 `claude-sonnet-4-6`으로 설정

### 2-2. 핵심 설정값 (settings.json)

`⌘ + Shift + P` → **"Open User Settings (JSON)"** → 아래 설정 추가:

```json
{
  // Cursor AI 설정
  "cursor.general.enableShadowWorkspace": true,
  "cursor.cpp.enablePartialAccepts": true,

  // 자동완성 설정
  "editor.inlineSuggest.enabled": true,
  "editor.suggest.preview": true,
  "editor.tabCompletion": "on",

  // Nuxt 4 / Vue 3 최적화
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[vue]": {
    "editor.defaultFormatter": "Vue.volar"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // TypeScript 설정
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,

  // 파일 제외 (성능 향상)
  "files.exclude": {
    "**/.nuxt": true,
    "**/.output": true,
    "**/node_modules": true,
    "**/.git": true
  },

  // Tailwind CSS IntelliSense
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}
```

### 2-3. 권장 익스텐션

VS Code에서 사용하던 익스텐션이 이전되지 않은 경우 수동 설치:

```
# 필수
Vue.volar                    # Vue - Official (Nuxt 4 TypeScript 지원)
esbenp.prettier-vscode       # Prettier
dbaeumer.vscode-eslint       # ESLint
bradlc.vscode-tailwindcss    # Tailwind CSS IntelliSense

# 선택
antfu.iconify                # Iconify 아이콘
antfu.unocss                 # UnoCSS (선택)
```

---

## 3. Nuxt 4 프로젝트 설정

### 3-1. .cursorrules 파일 적용

프로젝트 루트에 `.cursorrules` 파일을 생성하면 Cursor가 해당 규칙을 모든 AI 응답에 적용합니다.

> 템플릿: `docs/cursorrules-template.md` 참조
> 실제 파일: 프로젝트 루트 `.cursorrules`로 복사 후 사용

### 3-2. .cursor/rules/ 디렉토리 방식 (권장 - Cursor 0.45+)

최신 Cursor는 `.cursor/rules/` 디렉토리 내 여러 `.mdc` 파일로 규칙을 분리할 수 있습니다:

```
.cursor/
└── rules/
    ├── nuxt4-conventions.mdc   # Nuxt 4 디렉토리 및 컨벤션
    ├── typescript-rules.mdc    # TypeScript strict 규칙
    ├── vue-components.mdc      # Vue 컴포넌트 작성 패턴
    └── tailwind-patterns.mdc   # Tailwind CSS v4 패턴
```

`.mdc` 파일 예시 (`nuxt4-conventions.mdc`):
```
---
description: Nuxt 4 프로젝트 구조 및 컨벤션
globs: **/*.vue, **/*.ts
---
# Nuxt 4 컨벤션

- 앱 코드는 반드시 `app/` 디렉토리 하위에 위치
- 컴포넌트: `app/components/`, 페이지: `app/pages/`
- `any` 타입 사용 금지, `unknown` 또는 명시적 타입 사용
```

### 3-3. 프로젝트 인덱싱 확인

1. Cursor 하단 상태바 → **"Indexing"** 완료 확인
2. 완료 후 `@codebase` 명령으로 전체 프로젝트 컨텍스트 참조 가능

---

## 4. 주요 기능 및 단축키

### 4-1. 핵심 기능

| 기능 | 단축키 | 설명 |
|------|--------|------|
| AI Chat | `⌘ + L` | 우측 사이드바 AI 채팅 |
| Composer | `⌘ + I` | 멀티파일 편집 (핵심 기능) |
| 인라인 편집 | `⌘ + K` | 선택 영역 인라인 수정 |
| 자동완성 수락 | `Tab` | AI 제안 수락 |
| 자동완성 거부 | `Esc` | AI 제안 무시 |
| 부분 수락 | `⌘ + →` | 단어 단위 부분 수락 |

### 4-2. Composer 활용 (멀티파일 편집)

`⌘ + I` 로 Composer 실행 후:

```
@codebase 를 참고해서 app/components/UserCard.vue 컴포넌트를 생성해줘.
- Props: userId(string), showAvatar(boolean, 기본값 true)
- TypeScript strict 모드 준수
- Tailwind CSS v4 스타일 적용
- 관련 테스트 파일도 함께 생성
```

### 4-3. 컨텍스트 참조 문법

| 문법 | 설명 |
|------|------|
| `@파일명` | 특정 파일 참조 (예: `@app/app.vue`) |
| `@codebase` | 프로젝트 전체 인덱스 참조 |
| `@docs` | 연동된 공식 문서 참조 |
| `@web` | 실시간 웹 검색 |
| `@git` | Git 커밋 히스토리 참조 |

---

## 5. Nuxt 4 개발 프롬프트 패턴

### 5-1. Vue 컴포넌트 생성

```
app/components/[ComponentName].vue 파일을 생성해줘.

요구사항:
- Props 인터페이스를 TypeScript로 명시적으로 정의 (any 금지)
- <script setup lang="ts"> 사용
- Tailwind CSS v4 반응형 클래스 적용 (sm/md/lg 브레이크포인트)
- shadcn-vue 컴포넌트 활용 가능

기능: [기능 설명]
```

### 5-2. Pinia 스토어 생성

```
stores/use[StoreName]Store.ts 파일을 Composition API 방식으로 생성해줘.

- defineStore("storeName", () => { ... }) 형식 사용
- 상태(ref/reactive), 게터(computed), 액션(function) 구조 준수
- TypeScript 타입 명시
- 필요한 경우 useFetch 또는 useAsyncData 활용

스토어 역할: [역할 설명]
```

### 5-3. Vitest 테스트 작성

```
@app/components/[ComponentName].vue 를 참고해서 Vitest 테스트를 작성해줘.

- @nuxt/test-utils의 mountSuspended 사용
- 주요 props 조합에 대한 렌더링 테스트
- 사용자 인터랙션 테스트 (클릭, 입력 등)
- 엣지 케이스 포함 (빈 값, 최대값 등)
```

### 5-4. 서버 API 엔드포인트 생성

```
server/api/[endpoint].ts Nitro API 라우트를 생성해줘.

- defineEventHandler 사용
- 요청 바디/쿼리 파라미터 TypeScript 타입 정의
- 에러 처리 (createError 활용)
- 응답 타입 명시

엔드포인트 역할: [역할 설명]
```

### 5-5. 코드 리뷰 요청

```
@app/components/[ComponentName].vue 코드를 리뷰해줘.

체크리스트:
- TypeScript any 타입 사용 여부
- 반응형 디자인 적용 여부 (Tailwind 브레이크포인트)
- Vue 3 Composition API 베스트 프랙티스 준수
- 불필요한 리렌더링 유발 요소
- 접근성(a11y) 이슈
```

---

## 6. 외부 문서 연동 (@docs)

Cursor Settings → **Features** → **Docs** 탭에서 추가:

| 문서명 | URL |
|--------|-----|
| Nuxt 4 공식 문서 | `https://nuxt.com/docs` |
| Vue 3 공식 문서 | `https://vuejs.org/guide` |
| Tailwind CSS v4 | `https://tailwindcss.com/docs` |
| shadcn-vue | `https://www.shadcn-vue.com` |
| Pinia | `https://pinia.vuejs.org` |
| Vitest | `https://vitest.dev` |

등록 후 `@Nuxt 4 공식 문서` 형태로 AI 채팅에서 참조 가능

---

## 7. 팀 설정 공유

### .cursor/ 디렉토리를 Git으로 관리

```bash
# .gitignore에서 제외 (팀 공유 대상)
# .cursor/rules/ 는 커밋 대상

# .gitignore 예시
.cursor/mcp.json       # MCP 서버 설정 (로컬 전용)
```

### 팀 공유 설정 체크리스트

- [ ] `.cursorrules` 또는 `.cursor/rules/` 파일 커밋
- [ ] `docs/cursor-setup-guide.md` 팀 위키 등록
- [ ] 팀원 계정 초대 (팀 플랜 사용 시)
- [ ] 권장 익스텐션 목록 공유

---

## 8. 주의사항 및 팁

### 보안 주의사항

> `.cursorrules`에 API 키, 비밀번호, 개인정보를 **절대 포함하지 마세요**.
> AI 컨텍스트로 전송되어 외부 서버에 노출될 수 있습니다.

### 성능 팁

- 대형 프로젝트에서 인덱싱 속도가 느린 경우 `files.exclude`에 불필요한 디렉토리 추가
- `.nuxt`, `.output`, `node_modules`는 기본 제외 권장

### 비용 절약 팁

- 단순 자동완성: `claude-haiku-4-5` 사용 (빠르고 저렴)
- 복잡한 리팩토링: `claude-sonnet-4-6` 사용
- `@codebase` 남발 시 토큰 소비 증가 → 필요한 경우에만 사용

---

## 검토 이력

| 날짜 | 버전 | 변경 내용 | 작성자 |
|------|------|-----------|--------|
| 2026-03-19 | v1.0 | 최초 작성 | 시니어 Dev |