Cursor Rules 완전 가이드 — .cursorrules 잘 쓰는 법

Cursor를 쓰는데 매번 같은 말을 반복하고 있습니까. "TypeScript로 써줘", "함수명은 camelCase로", "테스트 코드도 같이". .cursorrules에 한 번 써두면 다시는 반복하지 않아도 됩니다.

[핵심 요약]
→ .cursorrules: 프로젝트 루트에 두는 Cursor 전용 지시 파일
→ 역할: 모든 AI 요청에 자동으로 적용되는 시스템 프롬프트
→ 범위: 프로젝트 전체 (글로벌) 또는 디렉토리별 (로컬)
→ 형식: 마크다운 텍스트 (구조화 권장)
→ Cursor 3: .cursor/rules/ 디렉토리로 확장 (다중 규칙 파일)
→ 효과: 코드 일관성, 반복 지시 제거, 팀 컨벤션 자동 적용

 

---

.cursorrules가 뭔지 30초 정리

없을 때:
사용자: "로그인 API 만들어줘"
Cursor: JavaScript로 작성, var 사용, 에러 처리 없음

.cursorrules 있을 때:
사용자: "로그인 API 만들어줘"
Cursor: TypeScript로 작성, async/await, Zod 검증,
        Jest 테스트 포함, 에러 핸들링 완비

→ 매번 지시하지 않아도 팀 컨벤션이 자동 적용됨

[.cursorrules vs CLAUDE.md 비교]

.cursorrules:
→ Cursor 전용
→ 프로젝트 루트 또는 디렉토리별
→ 마크다운 텍스트
→ Cursor AI 모든 요청에 자동 적용

CLAUDE.md:
→ Claude Code 전용
→ 레이어별 (글로벌/프로젝트/디렉토리)
→ 마크다운 텍스트
→ Claude Code 세션에 자동 로드

→ 둘 다 쓴다면 내용 싱크 맞추는 것 권장

---

실전 1 — 기본 .cursorrules 구조

<!-- .cursorrules (프로젝트 루트) -->

# 프로젝트 개요
Next.js 14 + TypeScript + Supabase 기반 SaaS 앱.
목표: 코드 일관성, 타입 안전성, 테스트 커버리지 80%+

---

## 기술 스택
- 언어: TypeScript (strict mode)
- 프레임워크: Next.js 14 App Router
- 스타일: Tailwind CSS
- DB: Supabase (PostgreSQL)
- 상태관리: Zustand
- 테스트: Jest + React Testing Library
- 패키지매니저: pnpm

---

## 코드 스타일 규칙

### 일반
- 함수명: camelCase
- 컴포넌트명: PascalCase
- 상수: UPPER_SNAKE_CASE
- 파일명: kebab-case.ts

### TypeScript
- any 사용 금지 → unknown 또는 명시적 타입
- 인터페이스는 I 접두어 없이 (User, not IUser)
- type vs interface: 객체는 interface, 유니온은 type

### 함수
- 순수 함수 선호
- 함수당 단일 책임
- 20줄 초과 시 분리 고려
- 비동기: async/await (Promise.then 지양)

---

## 컴포넌트 규칙

### 구조
```tsx
// 이 순서를 따를 것
import 문
type/interface 정의
컴포넌트 함수
export default

Props

• 필수 props: 명시적 타입
• 선택적 props: ? 사용
• children은 ReactNode 타입

---

API 규칙

• RESTful 엔드포인트 명명
• 에러 응답: { error: string, code: number }
• 성공 응답: { data: T, message?: string }
• 인증: Supabase Auth JWT

---

테스트 규칙

• 모든 유틸 함수: 단위 테스트 필수
• API 라우트: 통합 테스트 필수
• 컴포넌트: 핵심 인터랙션 테스트
• describe/it 패턴 사용
• 테스트 파일: *.test.ts(x)

---

금지 사항

• console.log (디버깅 후 반드시 제거)
• any 타입
• 하드코딩된 문자열 (상수로 분리)
• 인라인 스타일 (Tailwind 사용)
• default export in 유틸 파일

---

실전 2 — Cursor 3: .cursor/rules/ 다중 규칙 파일

Cursor 3부터는 단일 .cursorrules 대신 역할별로 분리된 규칙 파일을 지원합니다.

.cursor/
└── rules/
    ├── general.mdc          # 전체 프로젝트 공통 규칙
    ├── frontend.mdc         # 프론트엔드 전용
    ├── backend.mdc          # 백엔드 전용
    ├── testing.mdc          # 테스트 전용
    └── security.mdc         # 보안 전용

<!-- .cursor/rules/general.mdc -->
---
description: 모든 파일에 적용되는 공통 규칙
globs: ["**/*"]
alwaysApply: true
---

# 공통 규칙

## 언어
- 코드: 영어
- 주석: 한국어 (팀 내부용)
- 커밋 메시지: 영어 (Conventional Commits)

## 에러 처리
- try/catch 반드시 포함
- 에러 로깅: logger 유틸 사용 (console.log 금지)
- 사용자 노출 에러: 친절한 한국어 메시지

<!-- .cursor/rules/frontend.mdc -->
---
description: React/Next.js 컴포넌트 규칙
globs: ["src/components/**", "src/app/**"]
alwaysApply: false
---

# 프론트엔드 규칙

## 컴포넌트 작성
- Server Component 기본, Client Component 최소화
- use client는 상호작용 필요한 최하위 컴포넌트에만
- Suspense + ErrorBoundary 반드시 포함
- 로딩 상태 UI 항상 구현

## 접근성
- img: alt 필수
- button: aria-label 또는 텍스트 콘텐츠
- form: label 연결
- 색상만으로 정보 전달 금지

<!-- .cursor/rules/security.mdc -->
---
description: 보안 관련 규칙
globs: ["**/*"]
alwaysApply: true
---

# 보안 규칙

## 절대 금지
- API 키를 코드에 하드코딩
- 사용자 입력을 SQL에 직접 삽입
- eval() 사용
- dangerouslySetInnerHTML (불가피 시 반드시 sanitize)

## 필수
- 환경변수: .env.local (절대 커밋 금지)
- 사용자 입력: Zod로 검증
- API 라우트: 인증 미들웨어 적용
- 민감 데이터: 로그에 포함 금지

[.mdc 파일 메타데이터 옵션]
→ description: 규칙 설명 (Cursor가 언제 적용할지 판단에 사용)
→ globs: 적용 대상 파일 패턴
→ alwaysApply: true면 항상, false면 관련 파일일 때만

---

실전 3 — 스택별 템플릿

자주 쓰는 스택별 .cursorrules 템플릿입니다.

<!-- Next.js + TypeScript + Prisma 스택 -->

# 기술 스택
- Next.js 14 App Router
- TypeScript strict
- Prisma ORM
- PostgreSQL
- shadcn/ui

## 데이터베이스 규칙
- Prisma Client는 싱글톤 사용 (lib/prisma.ts)
- 모든 DB 쿼리: try/catch
- 트랜잭션: prisma.$transaction() 사용
- N+1 쿼리 금지: include로 사전 로드

## API Route 패턴
```ts
// 이 패턴을 항상 따를 것
export async function GET(request: Request) {
  try {
    // 인증 확인
    const session = await getServerSession()
    if (!session) return NextResponse.json(
      { error: "Unauthorized" }, { status: 401 }
    )

    // 비즈니스 로직
    const data = await prisma.user.findMany()

    return NextResponse.json({ data })
  } catch (error) {
    console.error(error)
    return NextResponse.json(
      { error: "Internal Server Error" }, { status: 500 }
    )
  }
}

컴포넌트 패턴

• shadcn/ui 컴포넌트 우선 사용
• 커스텀 컴포넌트: components/ui/ 에 배치
• 페이지 레벨: app/ 디렉토리
• 재사용 컴포넌트: components/ 디렉토리

<!-- FastAPI + Python 스택 -->

# 기술 스택
- Python 3.12+
- FastAPI
- SQLAlchemy 2.0 (async)
- Pydantic v2
- pytest

## Python 규칙
- 타입 힌트 필수 (모든 함수 파라미터, 반환값)
- Pydantic 모델로 입출력 검증
- async/await 일관 사용
- 함수명: snake_case
- 클래스명: PascalCase

## FastAPI 패턴
```python
# 이 패턴을 항상 따를 것
@router.post("/users", response_model=UserResponse)
async def create_user(
    user_data: UserCreate,
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_current_user)
) -> UserResponse:
    """사용자 생성 엔드포인트"""
    try:
        user = await user_service.create(db, user_data)
        return UserResponse.model_validate(user)
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))

테스트 규칙

• 모든 엔드포인트: pytest 테스트 필수
• DB 테스트: 트랜잭션 롤백으로 격리
• 픽스처: conftest.py에 정의

---

실전 4 — 팀 컨벤션 자동화

<!-- 팀 협업을 위한 .cursorrules -->

# 팀 컨벤션

## Git 커밋 메시지 (Conventional Commits)
코드 생성 시 관련 커밋 메시지도 제안할 것:
- feat: 새 기능
- fix: 버그 수정
- refactor: 리팩토링
- test: 테스트 추가
- docs: 문서 수정
- chore: 설정 변경

예시: feat(auth): add JWT refresh token rotation

## 코드 리뷰 기준
코드 작성 시 다음을 자체 점검할 것:
- [ ] 타입 안전성 확보
- [ ] 에러 처리 완비
- [ ] 테스트 코드 포함
- [ ] 성능 이슈 없음
- [ ] 보안 취약점 없음

## 디렉토리 구조 규칙
새 파일 생성 시 이 구조를 따를 것:

src/
├── app/ # Next.js 라우트
├── components/ # 재사용 컴포넌트
│ ├── ui/ # 기본 UI 컴포넌트
│ └── features/ # 기능별 컴포넌트
├── lib/ # 유틸리티, 설정
├── hooks/ # 커스텀 훅
├── types/ # TypeScript 타입
└── services/ # API 호출, 비즈니스 로직

## PR 체크리스트
PR 관련 코드 작성 시 자동으로 체크리스트 포함:
- 변경 목적 명확히 설명
- 테스트 커버리지 유지
- 스크린샷 첨부 (UI 변경 시)
- 관련 이슈 링크

---

실전 5 — 프레임워크별 최적화 팁

<!-- AI 코딩 에이전트 최적화 규칙 -->

# Cursor AI 사용 최적화

## 응답 품질 향상
- 코드 생성 시 항상 타입과 예시 포함
- 복잡한 로직은 단계별 주석으로 설명
- 여러 방법이 있으면 장단점과 함께 제시
- 레거시 패턴 발견 시 현대적 대안 제안

## 컨텍스트 활용
- @파일명으로 관련 파일 직접 참조
- 에러 메시지 전체 붙여넣기
- 변경 이유를 프롬프트에 포함

## 반복 작업 자동화
새 컴포넌트 생성 시 자동으로 포함할 것:
1. TypeScript 인터페이스
2. 기본 테스트 파일
3. Storybook 스토리 (UI 컴포넌트)
4. JSDoc 주석

새 API 라우트 생성 시:
1. 요청/응답 타입
2. 인증 미들웨어
3. 에러 핸들링
4. 단위 테스트

<!-- LLM 관련 프로젝트용 특화 규칙 -->

# AI/LLM 프로젝트 규칙

## 프롬프트 관리
- 프롬프트는 prompts/ 디렉토리에 YAML로 관리
- 하드코딩 금지 → 파일에서 로드
- 버전 관리 필수

## LLM 호출 패턴
```python
# 이 패턴을 항상 사용
async def call_llm(
    prompt: str,
    model: str = "claude-sonnet-4-6",
    max_tokens: int = 1024
) -> str:
    try:
        response = await client.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=[{"role": "user", "content": prompt}]
        )
        return response.content[0].text
    except anthropic.RateLimitError:
        await asyncio.sleep(60)
        return await call_llm(prompt, model, max_tokens)
    except Exception as e:
        logger.error(f"LLM 호출 실패: {e}")
        raise

비용 관리

• 프롬프트 캐싱 적극 활용
• 긴 컨텍스트: 요약 후 전달
• 배치 처리 가능한 작업은 배치 API 사용
• 토큰 사용량 로깅 필수

---

실전 6 — .cursorrules 작성 팁

[효과적인 .cursorrules 작성 원칙]

✅ 이렇게 써라:
→ 구체적으로: "에러 처리를 포함해줘" (X)
               "try/catch + logger.error() 필수" (O)
→ 예시 포함: 코드 패턴은 반드시 코드블록으로
→ 금지 명시: 하지 말아야 할 것도 명확히
→ 우선순위: 중요한 것을 앞에 배치
→ 간결하게: 너무 길면 LLM이 뒷부분 무시

❌ 이렇게 하지 마라:
→ 모호한 지시: "좋은 코드를 써줘"
→ 상충되는 규칙: "간결하게 + 항상 주석 포함"
→ 과도한 길이: 2000 토큰 이상은 효과 감소
→ 복사 붙여넣기: 실제 프로젝트에 맞게 커스터마이징

[최적 길이]
→ 기본 규칙: 500~1000 토큰
→ 복잡한 프로젝트: 최대 1500 토큰
→ 다중 파일(.cursor/rules/): 파일별 300~500 토큰

---

마무리

✅ .cursorrules 써야 할 때
→ 팀에서 Cursor를 공통으로 사용할 때
→ 매번 같은 지시를 반복하고 있을 때
→ 코드 스타일이 일관되지 않을 때
→ 새 팀원 온보딩 시 컨벤션 전달
→ 모노레포에서 디렉토리별 다른 규칙 필요할 때

[오늘 당장 시작하는 법]
1. 프로젝트 루트에 .cursorrules 생성
2. 현재 가장 자주 반복하는 지시 3개 적기
3. 기술 스택과 코드 패턴 예시 추가
4. 사용하면서 계속 업데이트

→ 완벽한 규칙 파일보다 지금 당장 3줄이라도 시작하는 게 낫다

 

관련 글 

https://cell-devlog.tistory.com/87

CLAUDE.md 잘 쓰는 법 — 세션마다 시니어 개발자를 고용하는 효과

https://cell-devlog.tistory.com/141

Cursor 3 완전 가이드 — Agents Window, Cloud Agents, Design Mode 실전 셋업

https://cell-devlog.tistory.com/59

매번 설명 반복하다 지쳤다면 — Claude Code 4레이어 컨텍스트 시스템

https://cell-devlog.tistory.com/39

AI 코딩 툴 3대장 완전 비교 — Cursor vs Claude Code vs GitHub Copilot