196 lines
6.1 KiB
Markdown
196 lines
6.1 KiB
Markdown
# .cursorrules 파일 템플릿 (Nuxt 4)
|
|
|
|
> 이 파일의 내용을 프로젝트 루트의 `.cursorrules` 파일로 복사하여 사용하세요.
|
|
> Cursor 0.45+ 사용 시 `.cursor/rules/` 디렉토리 방식을 권장합니다.
|
|
|
|
---
|
|
|
|
## 사용 방법
|
|
|
|
```bash
|
|
# 프로젝트 루트에 .cursorrules 파일 생성
|
|
cp docs/cursorrules-template.md .cursorrules
|
|
# 또는 아래 내용을 직접 .cursorrules에 붙여넣기
|
|
```
|
|
|
|
---
|
|
|
|
## .cursorrules 내용 (아래부터 복사)
|
|
|
|
```
|
|
# FE 팀 Nuxt 4 프로젝트 AI 코딩 규칙
|
|
# 마지막 업데이트: 2026-03-19
|
|
|
|
## 프로젝트 개요
|
|
- 프레임워크: Nuxt 4 (2025년 7월 안정 릴리즈)
|
|
- 언어: TypeScript (strict 모드, any 타입 사용 금지)
|
|
- CSS: Tailwind CSS v4
|
|
- UI 컴포넌트: shadcn-vue (shadcn/ui Vue 포트)
|
|
- 상태관리: Pinia (Composition API 방식)
|
|
- 테스트: Vitest + @nuxt/test-utils
|
|
- 패키지 매니저: pnpm
|
|
|
|
## 디렉토리 구조 (Nuxt 4)
|
|
앱 코드는 반드시 app/ 디렉토리 하위에 위치합니다:
|
|
- app/components/ → 재사용 컴포넌트 (PascalCase.vue)
|
|
- app/composables/ → 컴포저블 함수 (use로 시작)
|
|
- app/layouts/ → 레이아웃
|
|
- app/middleware/ → 라우트 미들웨어
|
|
- app/pages/ → 파일 기반 라우팅 (kebab-case)
|
|
- app/plugins/ → 플러그인
|
|
- app/stores/ → Pinia 스토어 (useXxxStore.ts)
|
|
- app/utils/ → 유틸리티 함수
|
|
- server/api/ → Nitro API 라우트
|
|
- shared/ → 클라이언트/서버 공유 코드
|
|
|
|
## 네이밍 컨벤션
|
|
- 변수/함수: camelCase
|
|
- 컴포넌트: PascalCase (파일명도 PascalCase.vue)
|
|
- 상수: UPPER_SNAKE_CASE
|
|
- 파일(페이지/기타): kebab-case
|
|
- Pinia 스토어: useXxxStore (예: useAuthStore, useCartStore)
|
|
- 컴포저블: useXxx (예: useUser, useCart)
|
|
|
|
## TypeScript 규칙
|
|
- any 타입 절대 금지 → unknown 또는 명시적 타입 사용
|
|
- 인터페이스는 Props, Emits 등 명시적으로 정의
|
|
- 제네릭 활용으로 타입 안전성 확보
|
|
- tsconfig.json의 strict: true 항상 유지
|
|
|
|
## Vue 컴포넌트 작성 규칙
|
|
- <script setup lang="ts"> 형식 사용 (Options API 금지)
|
|
- defineProps<Interface>() 형식으로 Props 타입 정의
|
|
- defineEmits<{ eventName: [payload: Type] }>() 형식 사용
|
|
- 컴포넌트 내 비즈니스 로직은 컴포저블로 분리
|
|
- 템플릿은 단순하게 유지, 복잡한 로직은 computed/methods로
|
|
|
|
## Tailwind CSS v4 규칙
|
|
- 인라인 스타일 대신 Tailwind 클래스 사용
|
|
- 반응형 디자인 필수: sm/md/lg/xl 브레이크포인트 활용
|
|
- 커스텀 색상은 tailwind.config.ts에 정의
|
|
- @apply 사용 최소화 (컴포넌트 레벨 스타일은 허용)
|
|
|
|
## shadcn-vue 컴포넌트 규칙
|
|
- Button, Input, Card 등 shadcn-vue 기본 컴포넌트 우선 사용
|
|
- 커스터마이징은 컴포넌트 래핑으로 처리
|
|
- app/components/ui/ 디렉토리에 위치
|
|
|
|
## Pinia 스토어 규칙
|
|
- Composition API 방식 필수: defineStore('id', () => { ... })
|
|
- 구조: 상태(ref/reactive) → 게터(computed) → 액션(function) 순서
|
|
- 스토어 간 직접 참조 최소화
|
|
|
|
## API 호출 규칙
|
|
- 서버사이드: useAsyncData 또는 useFetch 사용
|
|
- 클라이언트사이드: $fetch 사용
|
|
- 중복 요청 방지를 위한 key 파라미터 필수
|
|
|
|
## 코드 품질 규칙
|
|
- 함수는 단일 책임 원칙 준수
|
|
- 컴포넌트는 200줄 이하 유지 (초과 시 분리 검토)
|
|
- 주석은 한국어로 작성 (변수명/함수명은 영어)
|
|
- 커밋 메시지: "타입: 한국어 설명" 형식 (feat, fix, refactor 등)
|
|
|
|
## 테스트 규칙
|
|
- 컴포넌트 테스트: Vitest + mountSuspended (@nuxt/test-utils)
|
|
- 단위 테스트: 컴포저블, 유틸리티 함수 대상
|
|
- 테스트 파일: __tests__/ 또는 .spec.ts / .test.ts 확장자
|
|
|
|
## 금지 사항
|
|
- any 타입 사용
|
|
- Options API 사용 (Vue 3에서도 금지)
|
|
- 직접 DOM 조작 (ref 또는 Nuxt의 useNuxtApp 활용)
|
|
- console.log 프로덕션 코드 잔류
|
|
- 하드코딩된 URL (환경변수 사용)
|
|
- 민감 정보(API 키, 비밀번호)를 코드에 직접 작성
|
|
|
|
## AI 응답 시 우선순위
|
|
1. TypeScript 타입 안전성
|
|
2. Nuxt 4 app/ 디렉토리 구조 준수
|
|
3. 기존 코드 패턴과의 일관성
|
|
4. 성능 최적화
|
|
5. 가독성
|
|
```
|
|
|
|
---
|
|
|
|
## .cursor/rules/ 디렉토리 방식 (Cursor 0.45+)
|
|
|
|
더 세밀한 규칙 분리가 필요한 경우 아래 구조를 사용하세요:
|
|
|
|
### `.cursor/rules/nuxt4-conventions.mdc`
|
|
|
|
```markdown
|
|
---
|
|
description: Nuxt 4 디렉토리 구조 및 프로젝트 컨벤션
|
|
globs: app/**/*.vue, app/**/*.ts, server/**/*.ts
|
|
---
|
|
# Nuxt 4 프로젝트 컨벤션
|
|
|
|
## 디렉토리 구조
|
|
앱 코드는 반드시 app/ 디렉토리 하위에 위치합니다.
|
|
- app/components/ → PascalCase.vue
|
|
- app/pages/ → kebab-case.vue
|
|
- app/composables/ → useXxx.ts
|
|
- app/stores/ → useXxxStore.ts
|
|
|
|
## 네이밍
|
|
- 컴포넌트 파일: PascalCase.vue
|
|
- 페이지 파일: kebab-case.vue
|
|
- 컴포저블: useXxx (camelCase)
|
|
- 스토어: useXxxStore
|
|
```
|
|
|
|
### `.cursor/rules/typescript-strict.mdc`
|
|
|
|
```markdown
|
|
---
|
|
description: TypeScript strict 모드 규칙
|
|
globs: **/*.ts, **/*.vue
|
|
---
|
|
# TypeScript 규칙
|
|
|
|
- any 타입 절대 금지 → unknown 또는 명시적 타입 사용
|
|
- <script setup lang="ts"> 필수
|
|
- defineProps<Interface>() 형식 사용
|
|
- 모든 함수 파라미터와 반환값에 타입 명시
|
|
```
|
|
|
|
### `.cursor/rules/vue-components.mdc`
|
|
|
|
```markdown
|
|
---
|
|
description: Vue 3 컴포넌트 작성 패턴
|
|
globs: app/components/**/*.vue, app/pages/**/*.vue
|
|
---
|
|
# Vue 컴포넌트 패턴
|
|
|
|
- Composition API + script setup 필수 (Options API 금지)
|
|
- 비즈니스 로직은 app/composables/로 분리
|
|
- shadcn-vue 컴포넌트 우선 사용
|
|
- 컴포넌트 200줄 이하 유지
|
|
```
|
|
|
|
### `.cursor/rules/tailwind-patterns.mdc`
|
|
|
|
```markdown
|
|
---
|
|
description: Tailwind CSS v4 사용 패턴
|
|
globs: **/*.vue, **/*.html
|
|
---
|
|
# Tailwind CSS v4 패턴
|
|
|
|
- 인라인 스타일 금지, Tailwind 클래스 사용
|
|
- 반응형 필수: sm/md/lg/xl 브레이크포인트
|
|
- @apply 사용 최소화
|
|
- cn() 유틸리티로 조건부 클래스 처리
|
|
```
|
|
|
|
---
|
|
|
|
## 검토 이력
|
|
|
|
| 날짜 | 버전 | 변경 내용 | 작성자 |
|
|
|------|------|-----------|--------|
|
|
| 2026-03-19 | v1.0 | 최초 작성 | 시니어 Dev |
|