description: 프로젝트 전반 코드 생성 규칙 globs: */ alwaysApply: true

프로젝트 기본 규칙

언어 및 스타일

• TypeScript를 기본 언어로 사용한다.
• 모든 변수와 함수에 명시적 타입을 선언한다.
• 세미콜론을 항상 사용한다.
• 들여쓰기는 스페이스 2칸으로 한다.

네이밍 컨벤션

• 컴포넌트: PascalCase (예: UserProfile)
• 함수/변수: camelCase (예: getUserData)
• 상수: UPPER_SNAKE_CASE (예: MAX_RETRY_COUNT)
• 파일명: kebab-case (예: user-profile.tsx)

금지 패턴

컴포넌트 구조

• 함수형 컴포넌트만 사용한다.
• Props 인터페이스를 컴포넌트 위에 선언한다.
• 커스텀 훅은 use 접두사를 붙인다.

상태 관리

• 전역 상태는 Zustand를 사용한다.
• 서버 상태는 TanStack Query를 사용한다.
• 로컬 상태만 useState를 사용한다.

컴포넌트 템플릿

interface ComponentNameProps {
  title: string;
  onAction: () => void;
}

export const ComponentName = ({ title, onAction }: ComponentNameProps) => {
  return (
    
<h1>{title}</h1>
<button onClick={onAction}>실행</button>
    
  );
};
```</code></pre>
## Step 4: 커스텀 린팅 규칙 통합
<p>ESLint와 Prettier 설정을 Cursor Rules에 반영하여 AI가 생성하는 코드가 린팅을 통과하도록 합니다.
<code># .cursor/rules/linting-rules.mdc
---
description: 린팅 및 포맷팅 규칙
globs: **/*.ts, **/*.tsx
alwaysApply: true
---

# 린팅 규칙

## ESLint 연동
- import 순서: 외부 라이브러리 → 내부 모듈 → 상대 경로 → 타입 임포트
- 사용하지 않는 변수는 _ 접두사를 붙인다.
- React Hook 의존성 배열을 정확히 명시한다.

## Prettier 규칙 반영
- 줄 최대 길이: 100자
- 따옴표: 작은따옴표(single quote)
- 후행 쉼표: all
- 화살표 함수 괄호: always

## 코드 생성 시 import 순서 예시
```typescript
// 1. 외부 라이브러리
import { useState, useEffect } from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. 내부 모듈 (절대 경로)
import { Button } from '@/components/ui/button';
import { fetchUsers } from '@/lib/api';

// 3. 상대 경로
import { UserCard } from './user-card';

// 4. 타입
import type { User } from '@/types';
```</code></pre>
## Step 5: 팀 공유 프롬프트 템플릿 구성
<p>팀원 모두가 공통으로 사용할 프롬프트 패턴을 규칙 파일로 정의합니다.
<code># .cursor/rules/team-prompts.mdc
---
description: 팀 공유 프롬프트 템플릿
globs: **/*
alwaysApply: false
---

# 팀 프롬프트 템플릿

## API 엔드포인트 생성 시
- Zod 스키마로 요청/응답 유효성 검사를 포함한다.
- 에러 핸들링은 커스텀 AppError 클래스를 사용한다.
- 응답 형식은 { success: boolean; data: T; error?: string } 패턴을 따른다.

## 데이터베이스 쿼리 작성 시
- Prisma ORM을 사용한다.
- N+1 문제를 방지하기 위해 include를 적극 활용한다.
- 트랜잭션이 필요한 경우 prisma.$transaction을 사용한다.

## 테스트 코드 작성 시
- Vitest를 테스트 러너로 사용한다.
- describe → it 구조로 작성한다.
- 테스트 설명은 한국어로 작성한다.</code></pre>
## Step 6: Git으로 팀 전체 공유
<pre><code># .cursor/rules 디렉토리를 Git에 커밋
git add .cursor/rules/
git commit -m "feat: Cursor AI 규칙 파일 추가"
git push origin main</code></pre><p><code>.gitignore</code>에 <code>.cursor/rules/</code>가 포함되어 있지 않은지 반드시 확인하세요. 팀 공유가 목적이므로 반드시 버전 관리에 포함해야 합니다.

## 규칙 파일 구조 요약
<table><thead><tr><th>파일</th><th>역할</th><th>적용 범위</th></tr></thead><tbody><tr><td><code>project-general.mdc</code></td><td>프로젝트 전반 규칙</td><td>모든 파일</td></tr><tr><td><code>react-conventions.mdc</code></td><td>React/Next.js 패턴</td><td>.tsx, .ts 파일</td></tr><tr><td><code>linting-rules.mdc</code></td><td>린팅/포맷팅 규칙</td><td>.ts, .tsx 파일</td></tr><tr><td><code>team-prompts.mdc</code></td><td>팀 공유 템플릿</td><td>수동 적용</td></tr></tbody></table>
## Pro Tips: 파워 유저를 위한 고급 활용법
- **글로브 패턴 세분화:** <code>globs: src/api/**/*.ts</code>처럼 특정 디렉토리에만 규칙을 적용하면 AI가 컨텍스트를 더 정확히 파악합니다.- **alwaysApply 전략적 사용:** 핵심 규칙만 <code>alwaysApply: true</code>로 설정하고, 나머지는 <code>false</code>로 두어 AI가 관련 파일 작업 시에만 로드하도록 합니다. 토큰 낭비를 줄일 수 있습니다.- **네거티브 프롬프트 활용:** "~하지 마라" 형태의 규칙이 "~해라"보다 효과적인 경우가 많습니다. AI가 흔히 생성하는 안티패턴을 명시적으로 금지하세요.- **규칙 우선순위:** 여러 규칙 파일이 동일 파일에 적용될 경우, 더 구체적인 글로브 패턴의 규칙이 우선 적용됩니다.- **Cursor Settings 연동:** <code>Cursor Settings > Rules</code>에서 글로벌 규칙과 프로젝트 규칙을 함께 확인하고 우선순위를 관리할 수 있습니다.
## Troubleshooting: 자주 발생하는 문제와 해결법
<table><thead><tr><th>문제</th><th>원인</th><th>해결 방법</th></tr></thead><tbody><tr><td>규칙 파일이 적용되지 않음</td><td>파일 확장자가 <code>.mdc</code>가 아님</td><td>파일 확장자를 <code>.mdc</code>로 변경하고 프론트매터 형식 확인</td></tr><tr><td>특정 파일에서 규칙이 무시됨</td><td><code>globs</code> 패턴이 해당 파일과 매칭되지 않음</td><td>글로브 패턴을 수정하거나 <code>**/*</code>로 확장</td></tr><tr><td>규칙이 너무 많아 응답이 느림</td><td><code>alwaysApply: true</code> 파일이 과다</td><td>핵심 규칙만 <code>alwaysApply: true</code>로 유지, 나머지는 <code>false</code>로 전환</td></tr><tr><td>팀원에게 규칙이 보이지 않음</td><td><code>.gitignore</code>에 <code>.cursor/</code>가 포함됨</td><td><code>.gitignore</code>에서 <code>!.cursor/rules/</code> 예외 추가</td></tr><tr><td>레거시 <code>.cursorrules</code>와 충돌</td><td>두 가지 방식이 동시에 존재</td><td><code>.cursorrules</code> 내용을 <code>.cursor/rules/</code>로 마이그레이션 후 삭제</td></tr></tbody></table><!-- RELATED_CONTENT_PLACEHOLDER -->
## 자주 묻는 질문 (FAQ)

### Q1: .cursorrules 파일과 .cursor/rules/ 디렉토리 방식의 차이는 무엇인가요?
<code>.cursorrules</code>는 단일 파일에 모든 규칙을 작성하는 레거시 방식이고, <code>.cursor/rules/</code>는 역할별로 여러 <code>.mdc</code> 파일을 분리하여 관리하는 최신 방식입니다. 디렉토리 방식은 글로브 패턴과 <code>alwaysApply</code> 등 프론트매터 옵션을 지원하여 더 정교한 규칙 관리가 가능합니다. 새 프로젝트에서는 디렉토리 방식을 사용하세요.

### Q2: 규칙 파일의 내용이 AI 응답의 토큰을 소비하나요?
네, <code>alwaysApply: true</code>로 설정된 규칙 파일은 매 요청마다 컨텍스트에 포함되어 토큰을 소비합니다. 따라서 규칙은 간결하게 작성하고, 자주 참조가 필요하지 않은 규칙은 <code>alwaysApply: false</code>로 설정하여 관련 파일 작업 시에만 로드되게 하는 것이 효율적입니다.

### Q3: 개인 규칙과 팀 규칙을 분리할 수 있나요?
가능합니다. <code>.cursor/rules/</code> 디렉토리의 파일은 Git을 통해 팀과 공유하고, 개인 설정은 <code>Cursor Settings > Rules > User Rules</code>에서 관리합니다. 개인 규칙은 프로젝트가 아닌 사용자 레벨에서 적용되므로, 팀 규칙과 충돌 없이 개인 선호 스타일을 유지할 수 있습니다.