코드 스타일

• 모든 코드는 한국어 주석을 포함한다
• 변수명과 함수명은 영문 camelCase를 사용한다
• 커밋 메시지는 Conventional Commits 형식을 따른다
• console.log, print 등 디버그 출력은 제거 후 커밋한다

AI 동작 지침

프레임워크 컨벤션

• React Server Components를 기본으로 사용한다
• 클라이언트 컴포넌트에는 반드시 ‘use client’ 지시어를 추가한다
• 스타일링은 Tailwind CSS를 사용한다
• 상태 관리는 Zustand를 사용한다

자동완성 튜닝

• 컴포넌트 생성 시 TypeScript interface로 Props를 정의한다
• React.FC 대신 일반 함수 선언을 사용한다
• import 경로는 @/ 별칭을 사용한다

컴포넌트 패턴

// 권장 컴포넌트 패턴
interface ButtonProps {
  variant: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant, children, onClick }: ButtonProps) {
  return (
<button
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
</button>
  );
}
```</code></pre>
## 4단계: 백엔드 디렉토리 전용 규칙
<p><code>.cursor/rules/backend.mdc</code> 파일을 생성합니다.
<code>---
description: FastAPI 백엔드 코드 작성 규칙
globs: apps/api/**/*.py
alwaysApply: false
---

# 백엔드 규칙 (Python + FastAPI)

## API 설계
- 모든 엔드포인트에 Pydantic 모델로 요청/응답을 정의한다
- 비동기 함수(async def)를 기본으로 사용한다
- API 버저닝은 URL prefix(/v1/, /v2/)를 사용한다
- 환경변수는 pydantic-settings로 관리한다

## 데이터베이스
- ORM은 SQLAlchemy 2.0 스타일을 사용한다
- 마이그레이션은 Alembic으로 관리한다
- 쿼리 작성 시 N+1 문제를 항상 고려한다

## 코드 패턴
```python
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel

router = APIRouter(prefix="/v1/users", tags=["users"])

class UserResponse(BaseModel):
    id: int
    email: str
    name: str

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(user_id: int, db=Depends(get_db)):
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="사용자를 찾을 수 없습니다")
    return user
```</code></pre>
## 5단계: 인프라 코드 규칙 설정
<p><code>.cursor/rules/infra.mdc</code>에 Terraform/IaC 전용 규칙을 추가합니다.
<code>---
description: Terraform 인프라 코드 작성 규칙
globs: infra/**/*.tf
alwaysApply: false
---

# 인프라 규칙 (Terraform)

- 리소스 이름은 snake_case를 사용한다
- 모든 리소스에 태그(Environment, Team, Service)를 포함한다
- 시크릿 값은 변수로 분리하고 terraform.tfvars에 정의한다
- 모듈화를 적극 활용하여 재사용성을 높인다
- plan 결과를 반드시 리뷰 후 apply 한다</code></pre>
## 6단계: 테스트 전용 규칙 추가
<pre><code>---
description: 테스트 코드 작성 시 AI 동작 규칙
globs: **/*.test.{ts,tsx,py}, **/*.spec.{ts,tsx,py}, **/tests/**/*
alwaysApply: false
---

# 테스트 규칙

- 테스트 함수명은 "should_동작_when_조건" 패턴을 따른다
- 외부 API 호출은 반드시 모킹한다
- 각 테스트는 독립적으로 실행 가능해야 한다
- Given-When-Then 구조를 따른다
- 경계값과 에러 케이스를 반드시 포함한다</code></pre>
## 7단계: Git으로 팀 공유 설정
<p>규칙 파일을 버전 관리에 포함시켜 팀 전체가 동일한 AI 동작을 경험하도록 합니다.
<code># .cursor/rules를 커밋에 포함
git add .cursor/rules/
git commit -m "chore: Cursor AI 규칙 파일 추가"
git push origin main</code></pre><p>**주의:** <code>.cursorignore</code> 파일로 AI가 참조하지 않을 파일을 지정할 수 있습니다.
<code># .cursorignore 예시
node_modules/
.env
*.lock
dist/
build/</code></pre>
## 규칙 타입 비교표
<table><thead><tr><th>속성</th><th>Always Apply</th><th>Auto Attached</th><th>Agent Requested</th><th>Manual</th></tr></thead><tbody><tr><td>적용 방식</td><td>모든 컨텍스트에 자동 포함</td><td>glob 패턴 매칭 시 자동</td><td>AI가 필요 시 자동 요청</td><td>사용자가 @로 명시 호출</td></tr><tr><td>설정 키</td><td>alwaysApply: true</td><td>globs 패턴 지정</td><td>description 필수</td><td>별도 설정 없음</td></tr><tr><td>적합한 용도</td><td>팀 공통 컨벤션</td><td>디렉토리별 규칙</td><td>특수 상황 가이드</td><td>일회성 지침</td></tr></tbody></table>
## Pro Tips: 파워 유저를 위한 고급 활용법
- **규칙 상속 구조 활용:** 글로벌 규칙(alwaysApply: true)을 기반으로, 디렉토리 규칙(globs)이 추가 적용되어 세밀한 제어가 가능합니다.- **동적 컨텍스트 활용:** <code>@file</code>이나 <code>@folder</code> 참조를 규칙 내에서 활용하면 관련 코드를 AI 컨텍스트에 자동 포함시킬 수 있습니다.- **팀원별 로컬 오버라이드:** 개인 설정은 <code>.cursor/rules/local-*.mdc</code> 패턴으로 생성하고 <code>.gitignore</code>에 추가하여 충돌을 방지합니다.- **규칙 네이밍 컨벤션:** 파일명에 우선순위 번호를 붙여 로딩 순서를 명확히 합니다 (예: <code>01-global.mdc</code>, <code>02-frontend.mdc</code>).- **description 최적화:** Agent Requested 모드에서 AI가 규칙을 검색할 때 description을 기반으로 판단하므로, 구체적이고 명확하게 작성합니다.
## Troubleshooting: 자주 발생하는 문제 해결

### 규칙이 적용되지 않는 경우
- **원인:** glob 패턴이 실제 파일 경로와 불일치- **해결:** 상대 경로 기준으로 glob 패턴을 확인합니다. <code>apps/web/**/*</code>처럼 루트 기준 경로를 사용하세요.
### 규칙 간 충돌 발생
- **원인:** 여러 규칙의 globs가 동일한 파일에 매칭- **해결:** 더 구체적인 glob 패턴을 사용하거나, 충돌하는 지시사항을 하나의 규칙에 통합합니다.
### MDC 파일 문법 오류
- **원인:** frontmatter(YAML) 구분자 <code>---</code> 누락 또는 들여쓰기 오류- **해결:** 반드시 파일 최상단에 <code>---</code>로 시작하고 <code>---</code>로 끝나는 frontmatter 블록을 포함시키세요.
### AI가 규칙을 무시하는 느낌이 드는 경우
- **원인:** 규칙의 description이 모호하거나 alwaysApply 설정 누락- **해결:** 핵심 규칙은 <code>alwaysApply: true</code>로 설정하고, description을 구체적으로 작성합니다.<!-- RELATED_CONTENT_PLACEHOLDER -->
## 자주 묻는 질문 (FAQ)

### Q1: .cursor/rules 파일의 최대 크기 제한이 있나요?
<p>개별 규칙 파일에 공식적인 크기 제한은 없지만, 너무 긴 규칙은 AI의 컨텍스트 윈도우를 불필요하게 소모합니다. 한 파일당 500줄 이내로 유지하고, 주제별로 분리하는 것이 효과적입니다. 핵심 지시사항을 상단에 배치하여 우선적으로 처리되도록 합니다.

### Q2: 모노레포에서 패키지별로 다른 언어 규칙을 적용할 수 있나요?
네, globs 패턴으로 정확히 제어할 수 있습니다. 예를 들어 <code>apps/api/**/*.py</code>에는 Python 규칙을, <code>apps/web/**/*.tsx</code>에는 TypeScript/React 규칙을 별도로 적용합니다. 각 규칙 파일의 globs를 해당 디렉토리와 파일 확장자에 맞게 설정하면 Cursor가 자동으로 적절한 규칙을 활성화합니다.

### Q3: 팀원이 Cursor 대신 다른 에디터를 사용하면 규칙 파일이 영향을 주나요?
.cursor/rules 디렉토리는 Cursor 에디터 전용 설정이므로 VS Code나 다른 에디터 사용자에게는 아무런 영향을 미치지 않습니다. 프로젝트 루트에 존재하더라도 다른 도구와 충돌하지 않으며, 별도의 설정 없이 안전하게 Git에 커밋할 수 있습니다.