.cursorrules 완전 가이드: AI 코딩 어시스턴트 100% 활용하기

# .cursorrules

## 프로젝트 개요
[프로젝트 설명]

## 기술 스택
[사용 기술 명시]

## 코딩 규칙
[지켜야 할 규칙들]

## 금지 사항
[하면 안 되는 것들]

## 예시 패턴
[자주 쓰는 코드 패턴]

# .cursorrules

## 프로젝트 개요
한국 AI 리더보드 서비스. Next.js 14 App Router 기반.

## 기술 스택
- Next.js 14 (App Router, NOT Pages Router)
- TypeScript (strict mode)
- Tailwind CSS (CSS 파일 사용 금지)
- Prisma + PostgreSQL
- Zod (모든 입력 검증)
- React Query (서버 상태 관리)

## 컴포넌트 규칙
- 함수형 컴포넌트만 사용 (class 컴포넌트 금지)
- 'use client' 필요할 때만 사용 (기본은 서버 컴포넌트)
- Props 인터페이스는 컴포넌트 위에 선언
- 컴포넌트 파일명: PascalCase (예: UserCard.tsx)
- 유틸 함수 파일명: camelCase (예: formatDate.ts)

## TypeScript 규칙
- any 타입 금지 (unknown 또는 구체적 타입 사용)
- 모든 함수에 반환 타입 명시
- interface > type (객체는 interface 우선)
- enum 금지 (as const 또는 union 타입 사용)

## API 규칙
- API 라우트는 app/api/ 폴더에
- 모든 API 응답은 { data, error } 형식
- 에러는 NextResponse.json({ error: "..." }, { status: ... })

## 스타일 규칙
- Tailwind 유틸리티 클래스만 사용
- 긴 클래스는 cn() 헬퍼로 분리
- 반응형: mobile-first (sm:, md:, lg: 순서)
- 다크모드: dark: prefix 사용

## 금지 사항
- console.log 프로덕션 코드에 남기기
- var 키워드 사용
- 인라인 스타일 (style={{}})
- 하드코딩된 문자열 (상수로 분리)
- useEffect 의존성 배열 누락

## 폴더 구조
app/
  (auth)/          # 인증 필요 라우트 그룹
  (public)/        # 공개 라우트 그룹
  api/             # API 라우트
components/
  ui/              # 재사용 UI 컴포넌트
  features/        # 기능별 컴포넌트
lib/               # 유틸리티, 헬퍼
hooks/             # 커스텀 Hook
types/             # 타입 정의

## 코드 예시

### API 라우트 기본 패턴
'''typescript
export async function GET(req: Request): Promise<Response> {
  try {
    const data = await fetchData()
    return NextResponse.json({ data })
  } catch (error) {
    return NextResponse.json({ error: "Internal Server Error" }, { status: 500 })
  }
}
'''

### 서버 컴포넌트 기본 패턴
'''typescript
interface Props {
  id: string
}

export default async function Component({ id }: Props) {
  const data = await getData(id)
  return <div>{data.name}</div>
}
'''

# .cursorrules

## 프로젝트 개요
AI 데이터 수집 및 처리 파이프라인.

## 기술 스택
- Python 3.11+
- FastAPI (비동기 우선)
- Pydantic v2 (모든 모델 정의)
- SQLAlchemy 2.0 (async)
- PostgreSQL + pgvector

## 코딩 규칙
- 타입 힌트 필수 (모든 함수 파라미터와 반환값)
- async/await 우선 (동기 IO 금지)
- Pydantic 모델로 입출력 검증
- 환경변수는 pydantic-settings로 관리

## 네이밍
- 클래스: PascalCase
- 함수/변수: snake_case
- 상수: SCREAMING_SNAKE_CASE
- 파일: snake_case.py

## 에러 처리
- HTTPException 사용
- 커스텀 예외 클래스 정의 (app/exceptions.py)
- 절대 빈 except 사용 금지

## 금지 사항
- global 변수 사용
- 직접 SQL 문자열 조합 (SQLAlchemy ORM 사용)
- print() 대신 logging 모듈 사용
- 동기 requests 대신 httpx.AsyncClient 사용

## 코드 리뷰 기준
새 코드 작성 시 자동으로 이 항목을 체크하고
문제가 있으면 코드와 함께 경고를 출력하세요:

- [ ] SQL 인젝션 위험 없는가?
- [ ] API 키가 하드코딩되지 않았는가?
- [ ] 에러 처리가 있는가?
- [ ] 테스트 커버리지 고려됐는가?

## 자주 쓰는 패턴

### 로컬 이미지 최적화
항상 next/image를 사용하고 width/height를 명시하세요:
'''tsx
import Image from 'next/image'
<Image src="/hero.png" alt="설명" width={800} height={400} priority />
'''

### 날짜 포맷
date-fns 사용, 한국어 locale:
'''typescript
import { format } from 'date-fns'
import { ko } from 'date-fns/locale'
format(new Date(), 'yyyy년 MM월 dd일', { locale: ko })
'''

## 이 프로젝트에서 모르면 안 되는 것들

### 데이터 모델 핵심 관계
- User → Post (1:N)
- Post → Tag (N:M, PostTag 조인 테이블)
- Article.summaryKo = 본문 전체 (별도 content 컬럼 없음)

### 절대 바꾸면 안 되는 것
- Article.summaryKo 컬럼 구조
- User 인증 미들웨어 (middleware.ts)
- /api/webhooks/* 엔드포인트 (외부 연동)

.cursor/
  rules/
    general.mdc          # 전체 프로젝트 규칙
    frontend.mdc         # 프론트엔드 규칙
    backend.mdc          # 백엔드 규칙
    database.mdc         # DB/쿼리 규칙

---
globs: ["**/*.tsx", "**/*.ts"]
---
# 프론트엔드 규칙
...