fe-agent/docs/cursorrules-template.md

.cursorrules 파일 템플릿 (Nuxt 4)

이 파일의 내용을 프로젝트 루트의 .cursorrules 파일로 복사하여 사용하세요. Cursor 0.45+ 사용 시 .cursor/rules/ 디렉토리 방식을 권장합니다.

---

사용 방법

# 프로젝트 루트에 .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

---
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

---
description: TypeScript strict 모드 규칙
globs: **/*.ts, **/*.vue
---
# TypeScript 규칙

- any 타입 절대 금지 → unknown 또는 명시적 타입 사용
- <script setup lang="ts"> 필수
- defineProps<Interface>() 형식 사용
- 모든 함수 파라미터와 반환값에 타입 명시

.cursor/rules/vue-components.mdc

---
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

---
description: Tailwind CSS v4 사용 패턴
globs: **/*.vue, **/*.html
---
# Tailwind CSS v4 패턴

- 인라인 스타일 금지, Tailwind 클래스 사용
- 반응형 필수: sm/md/lg/xl 브레이크포인트
- @apply 사용 최소화
- cn() 유틸리티로 조건부 클래스 처리

---

검토 이력

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