Cursor Rules 완벽 가이드 — .cursorrules 작성법부터 프로젝트별 AI 코딩 규칙 최적화까지

Cursor Rules란 무엇인가? AI 코딩의 기본 규칙 설정

Cursor는 AI 기반 코드 에디터로, 인공지능이 코드를 생성하고 수정할 때 따를 규칙을 정의하는 기능을 제공합니다. 이를 .cursorrules 파일이라고 부르는데, 프로젝트의 코딩 표준, 아키텍처 패턴, 그리고 AI가 생성해야 할 코드의 스타일을 명시적으로 정의하는 설정 파일입니다.

.cursorrules 파일이 중요한 이유는 간단합니다. AI 코딩 도구를 사용할 때 방향성 없이 맡기면 예상 밖의 코드가 생성될 수 있습니다. 예를 들어, 프로젝트에서 함수형 프로그래밍 패턴을 원하는데 클래스 기반 코드가 나온다면 나중에 리팩토링 비용이 발생합니다. 하지만 .cursorrules 파일에 명확한 규칙을 정의하면 Cursor AI는 처음부터 당신의 프로젝트 규칙에 맞춘 코드를 생성하게 됩니다.

실제로 많은 개발팀에서 .cursorrules를 프로젝트의 Single Source of Truth로 활용하고 있습니다. 팀원이 바뀌거나 새로운 개발자가 합류해도 .cursorrules 파일만 보면 프로젝트의 코딩 스탠다드를 즉시 파악할 수 있기 때문입니다.

.cursorrules 파일의 위치 및 생성 방법

.cursorrules 파일은 프로젝트 루트 디렉토리에 위치해야 합니다. Cursor 에디터는 프로젝트를 열 때 자동으로 프로젝트 루트의 .cursorrules 파일을 찾아 로드합니다.

파일 생성 단계

1. 프로젝트 루트 디렉토리로 이동합니다.
2. `.cursorrules` 파일을 새로 생성합니다. (확장자 없음)
3. 텍스트 에디터(VS Code, Cursor, 등)로 파일을 열고 규칙을 작성합니다.
4. 파일을 저장하고, Cursor를 재시작하거나 새로운 탭을 열면 규칙이 적용됩니다.

참고: 파일명은 정확히 `.cursorrules`여야 합니다(점으로 시작). 다른 이름으로 하면 Cursor가 인식하지 않습니다.

파일 위치 예시

my-project/
├── .cursorrules          ← 이 위치에 있어야 함
├── src/
├── public/
├── package.json
└── README.md

.cursorrules 기본 문법과 지시어 종류

.cursorrules 파일은 기본적으로 마크다운(Markdown) 또는 일반 텍스트 형식으로 작성됩니다. 특별한 프로그래밍 문법이 아니라 인간이 읽을 수 있는 형태의 규칙 설명이 핵심입니다.

기본 문법 구조

.cursorrules 파일은 다양한 섹션으로 구성될 수 있습니다:

# 프로젝트 개요
프로젝트의 목적과 핵심 기술 스택을 설명합니다.

## 코딩 스타일
- 들여쓰기: 2칸 또는 4칸
- 세미콜론 사용 여부
- 네이밍 컨벤션

## 프로젝트 구조
src/ 디렉토리 구조와 각 폴더의 역할을 설명합니다.

## 금지 패턴
피해야 할 패턴과 구현 방식을 명시합니다.

## 필수 라이브러리
프로젝트에서 사용할 의존성과 버전을 명시합니다.

## 파일 참조
기존 코드 패턴이나 예시 파일을 링크합니다.

주요 지시어

.cursorrules에서 자주 사용되는 지시어들:

• DO: 반드시 따를 규칙
• DON'T: 피해야 할 패턴
• ALWAYS: 항상 적용할 규칙
• NEVER: 절대 하면 안 되는 일
• EXAMPLE: 구체적인 코드 예시
• REFERENCE: 참조할 파일이나 문서

실전 .cursorrules 예시

예시 1: React + TypeScript 프로젝트

# React + TypeScript Project Rules

## 프로젝트 개요
- 프레임워크: React 18+
- 언어: TypeScript
- 상태 관리: Zustand
- 스타일링: Tailwind CSS
- 번들러: Vite

## 코딩 스타일
- 들여쓰기: 2칸
- 세미콜론 사용 (필수)
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- Props는 인터페이스로 정의 (type 금지)

## 파일 구조
```
src/
├── components/     (재사용 가능한 UI 컴포넌트)
├── hooks/          (커스텀 React 훅)
├── store/          (Zustand 상태 관리)
├── pages/          (페이지 컴포넌트)
├── utils/          (유틸리티 함수)
└── types/          (타입 정의)
```

## 필수 규칙

### DO
- 모든 컴포넌트에 PropTypes 또는 TypeScript 인터페이스 사용
- 상태 관리는 Zustand 스토어를 사용
- 커스텀 훅으로 로직 분리 (hooks 폴더)
- Tailwind 클래스로만 스타일링
- API 호출은 utils/api.ts 에서 관리

### DON'T
- props drilling 사용 (상태 관리 사용)
- inline 스타일 사용
- 컴포넌트 안에 API 로직 작성
- any 타입 사용

### ALWAYS
- 컴포넌트 파일명은 PascalCase
- 유틸 함수 파일명은 camelCase
- 타입 인터페이스명은 I로 시작 (e.g., IButtonProps)

## 예시 코드

// ❌ 하지 말 것
const MyComponent = ({ data }: any) => {
  return <div style={{ color: 'red' }}>{data}</div>;
};

// ✅ 올바른 형식
interface IMyComponentProps {
  data: string;
  onSubmit?: (value: string) => void;
}

const MyComponent: React.FC<IMyComponentProps> = ({
  data,
  onSubmit,
}) => {
  return (
    <div className="text-red-600">
      {data}
    </div>
  );
};

예시 2: Python 백엔드 프로젝트

# Python FastAPI Backend Rules

## 프로젝트 개요
- 프레임워크: FastAPI
- 언어: Python 3.11+
- 데이터베이스: PostgreSQL
- ORM: SQLAlchemy
- 인증: JWT

## 코딩 스타일
- PEP 8 준수
- 들여쓰기: 4칸
- 타입 힌팅 필수
- Docstring: Google 스타일

## 프로젝트 구조
```
src/
├── api/            (라우터)
├── models/         (데이터베이스 모델)
├── schemas/        (Pydantic 스키마)
├── services/       (비즈니스 로직)
├── utils/          (유틸리티)
├── config.py       (설정)
└── main.py         (메인 앱)
```

## 필수 규칙

### DO
- 모든 함수에 타입 힌팅 추가
- FastAPI 라우터를 별도 파일에서 정의
- Pydantic 스키마로 요청/응답 검증
- 데이터베이스 접근은 services 레이어를 통해
- 에러 처리: HTTPException 사용
- 로깅: logging 모듈 사용

### DON'T
- routes 폴더에서 직접 데이터베이스 접근
- 전역 변수로 데이터 공유
- 하드코딩된 설정값
- try-except로 모든 에러 무시

### ALWAYS
- 함수명과 변수명은 snake_case
- 클래스명은 PascalCase
- 상수는 UPPER_SNAKE_CASE
- 엔드포인트는 /api/v1/ 형식

## 예시 코드

# ❌ 하지 말 것
@app.get("/users")
def get_users():
    users = db.query(User).all()
    return users

# ✅ 올바른 형식
from fastapi import HTTPException, status
from sqlalchemy.orm import Session

@app.get("/api/v1/users", response_model=list[UserSchema])
async def get_users(
    skip: int = 0,
    limit: int = 10,
    db: Session = Depends(get_db)
) -> list[UserSchema]:
    """
    모든 사용자를 조회합니다.

    Args:
        skip: 스킵할 결과 수
        limit: 반환할 최대 결과 수
        db: 데이터베이스 세션

    Returns:
        사용자 목록
    """
    try:
        users = db.query(User).offset(skip).limit(limit).all()
        return users
    except Exception as e:
        logger.error(f"사용자 조회 실패: {str(e)}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail="사용자 조회에 실패했습니다."
        )

예시 3: Next.js + TypeScript 웹앱

# Next.js 14 App Router Rules

## 프로젝트 개요
- 프레임워크: Next.js 14
- 언어: TypeScript
- 스타일링: Tailwind CSS
- 상태관리: React Context + Custom Hooks
- API: API Routes

## 파일 구조
```
app/
├── (auth)/          (인증 관련 라우트)
├── (dashboard)/     (대시보드 라우트)
├── api/             (API 라우트)
├── layout.tsx       (루트 레이아웃)
└── page.tsx         (홈페이지)

components/
├── ui/              (기본 UI 컴포넌트)
├── layout/          (레이아웃 컴포넌트)
└── features/        (기능별 컴포넌트)

lib/
├── utils.ts         (유틸리티)
└── api-client.ts    (API 클라이언트)
```

## 코딩 스타일
- 들여쓰기: 2칸
- 세미콜론 생략
- Server Components 우선 사용
- Client Components는 'use client' 명시

## 필수 규칙

### DO
- 모든 페이지와 컴포넌트에 TypeScript 사용
- 서버 컴포넌트를 기본으로 사용
- API 라우트는 /api 폴더에만 작성
- 환경변수는 .env.local에 정의
- 이미지는 next/image 사용
- 동적 라우트는 [id].tsx 형식

### DON'T
- props drilling (Context 또는 hooks 사용)
- require() 문 사용 (import 사용)
- 클라이언트 전용 라이브러리를 서버 컴포넌트에서 사용
- 직접 데이터베이스 접근

### ALWAYS
- 모든 컴포넌트에 명확한 타입 정의
- API 응답에 타입 정의
- 폼은 React Hook Form 사용
- 검증은 Zod 라이브러리 사용

## 예시 코드

// app/dashboard/page.tsx
import { Metadata } from 'next'
import { DashboardClient } from '@/components/dashboard-client'

export const metadata: Metadata = {
  title: '대시보드',
  description: '사용자 대시보드'
}

export default function DashboardPage() {
  return (
    <main className="container mx-auto py-8">
      <h1 className="text-3xl font-bold">대시보드</h1>
      <DashboardClient />
    </main>
  )
}

// components/dashboard-client.tsx
'use client'

import { useState } from 'react'
import { useUser } from '@/hooks/useUser'

interface IDashboardClientProps {}

export function DashboardClient({}: IDashboardClientProps) {
  const { user, loading } = useUser()
  const [isOpen, setIsOpen] = useState(false)

  if (loading) return <div>로딩 중...</div>

  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
      <div className="bg-white p-6 rounded-lg shadow">
        <h2 className="text-lg font-semibold">프로필</h2>
        <p>{user?.name}</p>
      </div>
    </div>
  )
}

자주 쓰는 규칙 패턴과 베스트 프랙티스

코딩 스타일 규칙

모든 프로젝트에서 일관성을 유지하기 위해 코딩 스타일을 명시적으로 정의하는 것이 중요합니다:

## 코딩 스타일 규칙

### 들여쓰기 및 포맷팅
- 들여쓰기: 2칸 (탭 금지)
- 줄 길이: 80-100자 이내
- 문자 인코딩: UTF-8

### 네이밍 컨벤션
- 변수/함수: camelCase (getUser, userName)
- 클래스/컴포넌트: PascalCase (UserCard, ApiClient)
- 상수: UPPER_SNAKE_CASE (MAX_RETRIES, API_TIMEOUT)
- 프라이빗 멤버: _로 시작 (_internalMethod)
- 불린값: is/has 접두사 (isActive, hasError)

### 주석 규칙
- 복잡한 로직은 반드시 주석 추가
- TODO/FIXME는 명확한 설명과 함께
- 함수 주석: JSDoc 형식 사용

금지 패턴 정의

AI가 생성하면 안 되는 패턴을 명시적으로 금지하는 것이 효과적합니다:

## 금지 패턴

### 절대 금지
- NEVER use eval() 함수
- NEVER hardcode credentials
- NEVER use console.log in production
- NEVER ignore error handling
- NEVER use any type in TypeScript
- NEVER mutate props directly

### 피해야 할 패턴
- Props drilling (상태 관리 사용)
- Inline styles (CSS 클래스 사용)
- Magic numbers (상수로 정의)
- Nested ternary operators (if-else 사용)
- Deep object nesting (분해 또는 helper 함수 사용)

### 대체 패턴
❌ Bad: props.user.profile.settings.theme.color
✅ Good: useTheme().color 또는 const { color } = useTheme()

파일 참조 및 예시 활용

기존 코드가 정확한 패턴을 보여줄 때, 파일을 직접 참조하면 AI가 더 정확하게 코드를 생성합니다:

## 코드 참조

### 컴포넌트 예시
- React 컴포넌트: src/components/Button.tsx 참조
- API 라우트: src/pages/api/auth.ts 참조
- 커스텀 훅: src/hooks/useAuth.ts 참조
- 유틸함수: src/utils/validation.ts 참조

### 구현 시 참조
새 컴포넌트를 만들 때:
1. src/components/Button.tsx 형식 따르기
2. src/hooks/useAuth.ts처럼 훅 구조 따르기
3. src/utils/validation.ts의 에러 처리 패턴 적용

### 금지된 참조 패턴
- 절대 node_modules 폴더의 코드 수정 금지
- 절대 .next 또는 build 폴더 수정 금지

프로젝트 유형별 최적화 팁

모노레포 프로젝트

여러 패키지가 포함된 모노레포에서는 각 패키지별로 규칙을 세부 정의하세요:

## 모노레포 구조

전체 프로젝트 규칙:
- root/.cursorrules (공통 규칙)

각 패키지별 규칙:
- packages/ui/.cursorrules
- packages/api/.cursorrules
- packages/web/.cursorrules

### 공통 규칙
- Git commit 메시지: conventional commits
- 버전 관리: semantic versioning
- 패키지 관리: pnpm/yarn workspace

### 패키지별 규칙
packages/ui/: 컴포넌트 라이브러리 규칙
packages/api/: 백엔드 API 규칙
packages/web/: 웹앱 규칙

마이크로서비스 환경

여러 서비스로 분리된 환경에서는 서비스별 규칙을 명확히 하세요:

## 마이크로서비스 규칙

### 공통 규칙
- API: REST + OpenAPI 3.0 문서화
- 에러 처리: 표준화된 에러 코드
- 로깅: JSON 형식, 구조화된 로그
- 모니터링: Prometheus 메트릭 내보내기
- 헬스 체크: /health 엔드포인트 필수

### 서비스별 규칙
user-service/:
  - 인증/인가 로직 담당
  - 사용자 데이터 관리

order-service/:
  - 주문 처리 로직
  - 결제 통합

payment-service/:
  - 결제 처리
  - 거래 로깅

레거시 코드베이스

기존 코드와의 호환성을 유지하면서 새 코드를 추가할 때:

## 레거시 코드베이스 규칙

### 기존 코드 유지
- 기존 파일은 절대 수정하지 말 것 (예: legacy/auth.js)
- 새 기능은 항상 새 파일에 구현

### 점진적 마이그레이션
- 새 코드는 TypeScript + 최신 패턴
- 기존 코드는 JavaScript 유지
- 인터페이스 레이어로 양쪽 연결

### 예시
new/auth.ts          ← 새 TypeScript 구현
legacy/auth.js       ← 기존 JavaScript (수정 금지)
adapters/auth.ts     ← 호환성 레이어

트러블슈팅: .cursorrules가 작동하지 않을 때

문제 1: 파일을 생성했는데 Cursor가 인식하지 않음

해결방법:

• 파일명이 정확히 `.cursorrules`인지 확인하세요 (점으로 시작)
• 파일이 프로젝트 루트에 있는지 확인하세요
• Cursor를 완전히 재시작하세요
• 새로운 Cursor 윈도우를 열고 프로젝트를 다시 로드하세요

문제 2: .cursorrules 규칙이 일부만 적용됨

해결방법:

• Cursor 버전을 최신으로 업데이트하세요
• 파일 인코딩이 UTF-8인지 확인하세요
• 너무 복잡한 규칙은 분리하세요 (최대 10개 섹션)
• AI와 대화할 때 "@rules" 멘션으로 명시적으로 참조하세요

문제 3: 변경사항이 즉시 반영되지 않음

해결방법:

• .cursorrules 파일을 저장한 후 잠시 기다리세요 (1-2초)
• Cursor의 새로운 탭을 열거나 현재 탭을 새로고침하세요
• Cursor를 재시작하면 변경사항이 확실히 반영됩니다

문제 4: AI가 규칙을 무시하고 다른 패턴으로 코드 생성

해결방법:

• 규칙이 너무 모호하지 않은지 검토하세요
• 구체적인 코드 예시를 .cursorrules에 추가하세요
• "DO"와 "DON'T"를 명확히 구분하세요
• AI와 대화할 때 "다음 규칙을 따르세요: ..."로 명시적으로 재지시하세요

문제 5: 여러 개발자가 다른 .cursorrules 파일 사용

해결방법:

• .cursorrules는 버전 관리(Git)에 포함시키세요
• 모든 팀원이 동일한 파일을 사용하도록 명시하세요
• 변경사항이 생기면 Pull Request를 통해 리뷰하세요

.cursorrules 작성 시 실전 팁

1. 명확성이 최우선

AI는 애매한 표현을 다양하게 해석할 수 있으므로 명확해야 합니다:

❌ 애매함: "좋은 네이밍 규칙을 사용하세요"
✅ 명확함: "함수명은 camelCase, 클래스명은 PascalCase, 상수는 UPPER_SNAKE_CASE"

❌ 애매함: "에러를 잘 처리하세요"
✅ 명확함: "모든 API 호출은 try-catch로 감싸고, HTTPException으로 구체적인 에러 코드 반환"

2. 예시 코드는 필수

말보다 코드가 더 강력합니다. 좋은 예시와 나쁜 예시를 함께 제시하세요:

// ❌ 하지 말 것
const getUserData = async (id) => {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
};

// ✅ 올바른 형식
const getUserData = async (id: string): Promise<IUser> => {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    logger.error(`사용자 데이터 조회 실패: ${error}`);
    throw error;
  }
};

3. 정기적으로 검토하고 업데이트

.cursorrules는 살아있는 문서입니다. 프로젝트가 진화하면서 규칙도 함께 업데이트해야 합니다:

• 매달 한 번씩 .cursorrules를 검토하세요
• 팀원들의 피드백을 수집하세요
• 새로운 라이브러리나 패턴을 반영하세요
• 변경사항은 Git 히스토리에 기록하세요

4. 프로젝트 크기에 맞게 작성

작은 프로젝트와 큰 프로젝트의 규칙 수준을 다르게 하세요:

소규모 프로젝트 (1-2명): 기본 규칙만 (5-10개)

중규모 프로젝트 (3-10명): 상세 규칙 (10-20개)

대규모 프로젝트 (10명+): 여러 파일로 분리 + 상세 가이드

5. 팀 표준 공유

# 팀 표준 적용

## 공통 사항
모든 프로젝트는 다음 기본 규칙을 상속받습니다:
- 공사 시작: 프로젝트 루트의 .cursorrules 필수
- ESLint/Prettier: 린터 규칙과 동기화
- PR 검토: .cursorrules 변경 시 팀 리뷰 필수

## 프로젝트별 오버라이드
프로젝트 특성에 맞게 추가 규칙 정의 가능:
- 프론트엔드: UI 컴포넌트 규칙 추가
- 백엔드: API 설계 규칙 추가

마무리: .cursorrules로 AI 코딩 완벽 제어하기

.cursorrules는 단순한 설정 파일이 아닙니다. 이는 AI와 개발자 사이의 명확한 계약입니다. 프로젝트 규칙을 명시적으로 정의함으로써 다음을 얻을 수 있습니다:

• 생산성 향상: AI가 처음부터 올바른 코드를 생성하므로 리팩토링 시간 감소
• 코드 품질 유지: 일관된 스타일과 패턴으로 코드 리뷰 시간 단축
• 팀 협업 개선: 새 팀원도 .cursorrules만으로 프로젝트 표준 이해
• 유지보수 용이: 명확한 규칙이 있으면 나중에 코드 수정과 확장이 쉬움

지금 바로 프로젝트에 .cursorrules를 추가하고, 명확한 규칙을 정의해보세요. Cursor AI는 당신의 규칙을 최대한 따르려고 노력할 것입니다.

---

면책 고지: 이 글에 소개된 서비스와 도구는 작성 시점 기준이며, 업데이트에 따라 변경될 수 있습니다.