# devAlice — .cursorrules 템플릿 (Next.js + TypeScript)
#
# 위치: 프로젝트 루트의 .cursorrules 파일
# Cursor가 모든 채팅·편집·composer 호출 시 시스템 프롬프트로 자동 주입
#
# 적용:
#   1. 프로젝트 루트에 ".cursorrules" 이름으로 본 파일 저장
#   2. Cursor 재시작 (대부분 즉시 반영)
#
# 공식 문서: https://docs.cursor.com/context/rules-for-ai

# === 프로젝트 컨텍스트 ===

이 프로젝트는 Next.js 16 (App Router) + TypeScript strict + Tailwind CSS v4 + shadcn/ui 스택을 사용한다.
패키지 매니저는 pnpm 11이며, 의존성 추가 시 `pnpm add` 사용.

# === 코드 스타일 ===

- TypeScript strict. `any` 금지. 타입을 모르면 `unknown` 후 narrow.
- 파일명: 라우트는 kebab-case, 유틸/컴포넌트는 camelCase.
- 경로 별칭 `@/*` 사용 (상대 경로 `../../` 피하기).
- React 19 — `use client` 지시어는 정말 필요할 때만. 기본은 Server Component.
- 컴포넌트 prop은 inline type 또는 `Props` named type. interface는 라이브러리 인터페이스에만.

# === 라우팅 / 데이터 ===

- App Router. `app/{route}/page.tsx` 구조.
- 데이터 fetch는 Server Component에서 우선. Client 컴포넌트는 인터랙션 필요할 때만.
- ISR이 필요하면 `export const revalidate = N` (초 단위) 명시.
- 환경변수는 `process.env.NEXT_PUBLIC_*` (클라이언트 노출) vs 일반 (서버 전용) 분리.

# === 보안 ===

- 시크릿 하드코딩 금지. 코드에 API 키·토큰·비밀번호 리터럴 작성 거부.
- 사용자 입력은 경계에서 검증 (zod 또는 명시적 타입 가드).
- SQL/외부 API 호출 시 파라미터 바인딩 필수, 문자열 연결 금지.
- 에러 메시지에 내부 경로·스택 트레이스·DB 스키마 노출 금지.

# === 변경 범위 ===

- 요청받은 변경 범위 밖의 리팩토링 금지. "원래 코드가 이상해서 같이 고쳤습니다"는 안 됨.
- 미사용 import 정리는 OK. 미사용 변수 자동 삭제도 OK.
- 큰 구조 변경(파일 이동, 폴더 재구성)은 항상 사용자 승인 후.

# === 테스트 ===

- 새 기능 추가 시 단위 테스트도 함께. Vitest 사용.
- 테스트 파일은 동일 폴더에 `*.test.ts` 또는 `__tests__/`.
- assertion은 한 테스트당 명확한 한 가지에 집중.

# === 출력 형식 ===

- 코드 변경 제안 시 변경 의도 1-2문장 + diff 또는 전체 파일.
- 같은 효과를 내는 더 단순한 방법이 있으면 함께 제시.
- 외부 라이브러리 추가 제안 시 번들 사이즈와 대안 1개 함께.

# === 금지 항목 ===

- `console.log` 디버깅 코드를 production 코드에 남기지 않음.
- TODO 주석 남발 금지. 정말 추후 작업이면 별도 issue로.
- 주석은 WHAT이 아닌 WHY만. 코드를 읽으면 알 수 있는 내용은 주석 X.
- "이렇게도 할 수 있다"는 대안 5개 나열 금지. 권장안 1개 + 트레이드오프 1줄.

# === 도구 사용 ===

- 파일 검색은 grep으로. 전체 디렉토리 스캔 피하기.
- 큰 파일은 헤더/특정 범위만 읽기.
- 빌드/테스트 실행 후 raw output 첨부.