9.6 KiB
9.6 KiB
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. 다운로드 및 설치
- cursor.com 접속
- Download for Mac 클릭 (macOS 기준)
.dmg파일 실행 → Applications 폴더로 드래그
1-2. 기존 VS Code 설정 가져오기
최초 실행 시 "Import from VS Code" 선택:
- 익스텐션, 키바인딩, 테마, 설정이 자동으로 이전됩니다.
- 기존 VS Code 사용자는 적응 비용 최소화
1-3. 계정 연동
- Cursor 실행 → 우측 하단 프로필 아이콘 클릭
- Sign In → GitHub 계정으로 로그인 (권장)
- 팀 플랜 사용 시 초대 링크로 팀 워크스페이스 참여
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)" → 아래 설정 추가:
{
// 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. 프로젝트 인덱싱 확인
- Cursor 하단 상태바 → "Indexing" 완료 확인
- 완료 후
@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으로 관리
# .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 |