340 lines
9.6 KiB
Markdown
340 lines
9.6 KiB
Markdown
# 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 |
|