새로운 프로젝트 구조 및 개발 가이드라인 추가: .mcp.json, shrimp_data, shrimp-rules.md, Cursor 설정 가이드, 업무일지 템플릿, ROADMAP.md, 커밋 메시지 규칙 포함. 각 파일은 Nuxt 4 및 TypeScript strict 모드에 최적화된 개발 환경을 지원합니다.

2026-03-19 23:12:15 +09:00
commit d65bb12a15
10 changed files with 1502 additions and 0 deletions
--- a/docs/cursor-setup-guide.md
+++ b/docs/cursor-setup-guide.md
@@ -0,0 +1,339 @@
+# 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 |