Cursor Rules: 실제로 작동하는 .cursor/rules 파일 작성법

Cursor Rules: 실제로 작동하는 .cursor/rules 파일 작성법

모든 Cursor 사용자는 같은 장벽에 부딪힙니다. AI가 기술적으로는 작동하지만 프로젝트의 컨벤션을 무시하고, 잘못된 import 경로를 사용하며, outdated된 패턴을 적용하거나, 코드베이스의 나머지 부분과 전혀 다른 구조로 컴포넌트를 생성하는 경우입니다. Cursor 규칙은 AI에게 당신의 프로젝트가 어떻게 작동하는지에 대한 지속적인 컨텍스트를 제공하여 이를 해결합니다.

Cursor 규칙이란 무엇이며 왜 중요한가?

Cursor 규칙은 마크다운 파일로, 모든 AI 상호작용(채팅, 자동 완성, 코드 생성 등) 전에 주입되는 영구적인 시스템 프롬프트 역할을 합니다. 이를 AI를 위한 온보딩 문서라고 생각하세요. 매 세션마다 같은 실수를 수정하는 대신, 지시를 한 번 작성하면 그대로 유지됩니다.

이전의 접근 방식은 프로젝트 루트에 단일 .cursorrules 파일을 사용하는 것이었습니다. 이는 여전히 작동하지만 폐기되었습니다. 현재 시스템은 개별 .mdc(Markdown Cursor) 파일이 있는 .cursor/rules/ 디렉토리를 사용하며, 각 파일은 특정 상황에 맞게 범위가 지정됩니다. 모든 지시를 하나의 거대한 파일에詰め込む 대신 관심사별로 규칙을 분할하고, Cursor가 현재 수행 중인 작업과 관련된 규칙만 로드하므로 훨씬 더 나은 설정입니다.

AI 도구를 위한 컨텍스트 엔지니어링을 사용해 본 적이 있다면 개념이 익숙할 것입니다: 더 나은 입력 컨텍스트는 극적으로 더 나은 출력을 만들어냅니다. 규칙은 전체 개발 워크플로우를 위한 컨텍스트 엔지니어링입니다.

첫 번째 규칙 파일 설정하기

프로젝트 루트에 .cursor/rules/ 디렉토리를 생성합니다:

mkdir -p .cursor/rules

각 규칙은 YAML 프론트매터와 그 뒤에 마크다운 콘텐츠가 포함된 .mdc 파일입니다. 기본 골격은 다음과 같습니다:

---
description: "When this rule should apply"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Your instructions go here in plain markdown.

세 가지 프론트매터 필드가 모든 것을 제어합니다:

Cursor 자체를 통해 규칙을 만들 수도 있습니다. 채팅에서 /create-rule을 입력하고 원하는 내용을 설명하면 됩니다. 하지만 직접 작성하면 더 많은 제어권을 가질 수 있습니다.

네 가지 규칙 유형 설명

규칙이 활성화되는 방식은 프론트매터 구성에 따라 달라집니다. 네 가지 모드가 있으며, 올바른 모드를 선택하는 것은 컨텍스트 윈도우 예산 관리에 중요합니다.

항상 적용 (Always Apply)

---
alwaysApply: true
---

모든 단일 AI 요청에 로드됩니다. 기술 스택 선언이나 모든 곳에 적용되는 중요한 컨벤션과 같은 프로젝트 전체의 기본 사항에 대해 신중하게 사용하세요. 항상 켜져 있는 모든 규칙은 관련 여부와 상관없이 모든 상호작용에서 토큰을 소모합니다.

자동 첨부 (글롭 기반)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

글롭 패턴과 일치하는 파일을 편집할 때만 활성화됩니다. 이것은 가장 많이 사용되는 규칙 유형입니다. 컴포넌트 파일에 있을 때는 React 컴포넌트 컨벤션이 로드되고, 라우트 핸들러에 있을 때는 API 패턴이 로드되며, 테스트를 작성할 때는 테스트 규칙이 로드됩니다.

에이전트 요청 (지능형)

---
description: "Database migration patterns using Drizzle ORM"
alwaysApply: false
---

글롭도 없고 항상 적용도 되지 않으며, 단지 설명만 있습니다. Cursor의 에이전트는 설명을 읽고 현재 작업에 규칙이 관련되어 있는지 결정합니다. 마이그레이션을 작성하라고 요청하면 이 규칙을 가져옵니다. 버튼 스타일을 지정 중이라면 건너뜁니다. 파일 경로에 깔끔하게 매핑되지 않는 규칙에 대해 놀랍도록 잘 작동합니다.

수동 (Manual)

---
---

프론트매터 필드가 설정되지 않았거나(또는 빈 프론트매터). 이러한 규칙은 채팅에서 @rule-name으로 명시적으로 언급할 때만 활성화됩니다. 배포 체크리스트나 가끔만 필요한 리팩토링 가이드처럼 редко 사용되지만 중요한 지시에 적합합니다.

실제로 작동하는 글롭 패턴

글롭은 자동 첨부 규칙을 트리거하는 파일을 결정합니다. 잘못 설정하면 규칙이 전혀 실행되지 않거나 모든 곳에서 실행됩니다. 다음은 작동하는 방법입니다:

# All TypeScript files in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Only component files
globs: ["**/components/**/*.tsx"]

# Python files, excluding tests
globs: ["**/*.py", "!**/test_*.py"]

# Multiple specific directories
globs: ["src/api/**", "src/services/**"]

실제 사용에서 주의할 몇 가지 사항:

• src/*는 한 디렉토리 레벨만 일치시킵니다. 재귀적 일치를 위해서는 거의 항상 src/**/*를 원합니다.
• *.js는 .jsx 또는 .ts 파일과 일치하지 않습니다. 확장자를 명시적으로 지정하세요.
• 글롭은 YAML 리스트여야 합니다. {src,lib}/**/*.ts와 같은 중괄호 구문은 조용히 실패할 수 있으므로 별도의 리스트 항목을 사용하세요.
• ! 접두사는 패턴을 제외하며, 생성된 파일이나 레거시 코드를 무시하는 데 유용합니다.

실용적인 규칙 예제

이론이 현실과 만나는 곳입니다. 이러한 규칙은 프로젝트에 즉시 적용하여 더 나은 AI 출력을 볼 수 있습니다.

프로젝트 전체 기본 규칙 (항상 적용)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

이를 30줄 미만으로 유지하세요. 모든 요청과 함께 로드되므로 모든 단어는 토큰 비용이 듭니다.

React 컴포넌트 규칙 (자동 첨부)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// 컴포넌트에서 직접 fetch, useEffect 없음
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Python API 규칙 (자동 첨부)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

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

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Go 서비스 규칙 (자동 첨부)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## 토큰 세금 관리하기

대부분의 Cursor 가이드가 건너뛰는 부분이 있습니다: 작성하는 모든 규칙은 토큰 비용이 듭니다. 항상 켜져 있는 규칙이 20개인 프로젝트는 AI가 코드를 보기 전에도 지시사항만으로 **요청당 2,000개 이상의 토큰**을 소모할 수 있습니다.

이는 Cursor의 채팅 컨텍스트가 표준 모드에서 약 20,000 토큰이기 때문에 중요합니다. 규칙이 그중 25%를 차지한다면, 실제 질문에 대한 AI의 '사고 공간'의 4분의 1을 잃은ことになります. 규칙이 쌓일수록, 특히 긴 대화에서 출력 품질이 저하되는 것을 느낄 수 있습니다.

토큰 예산을 건강하게 유지하는 세 가지 원칙:

**1. 자동 첨부 및 에이전트 요청 규칙을 적극적으로 사용하세요.** 프로젝트 스택 선언만 항상 켜져 있어야 합니다. 나머지는 조건부로 로드되어야 합니다. 해당 React 컴포넌트 규칙은 SQL 마이그레이션을 작성할 때 컨텍스트에 있을 필요가 없습니다.

**2. 장황하지 않게 밀도 있게 작성하세요.** "개발자가 공개 API 계약을 정의할 때 타입 별칭보다 TypeScript 인터페이스를 사용하는 것을 강력히 권장합니다"를 "공개 API에는 `type`보다 `interface`를 선호하세요."로 대체하세요. AI는 설득이 필요하지 않고 지시가 필요합니다.

**3. Rule of Three(세 번의 법칙)을 적용하세요.** AI가 세 번 잘못한 후에만 패턴을 규칙으로 코딩하세요. Cursor가 규칙 없이도 명명 규칙을 올바르게 처리한다면 규칙을 건너뛰세요. 불필요한 모든 규칙은 낭비된 컨텍스트입니다.

Cursor 채팅 패널 하단의 상태 표시줄에서 토큰 사용량을 모니터링할 수 있습니다. 100%에 가까워지는 것을 주의 깊게 살펴보세요. 그것이 정리해야 할 신호입니다.

## 실제 프로젝트를 위한 규칙 조직화

프로덕션 프로젝트는 일반적으로 5-8개의 규칙 파일이 필요합니다. 다음은 잘 작동하는 구조입니다:

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 lines)
  components.mdc      # React/Vue patterns, glob to component dirs
  api.mdc             # Backend conventions, glob to API dirs
  database.mdc        # ORM patterns, glob to models/migrations
  testing.mdc         # Test conventions, glob to test files
  deployment.mdc      # CI/CD patterns, manual trigger
  personal.mdc        # Your preferences (gitignored)

personal.mdc를 제외하고 모든 것을 버전 관리에 커밋하세요. 이렇게 하면 전체 팀이 동일한 AI 동작을 얻게 되며, 이것이 핵심 목적입니다. 한 Cursor 포럼 사용자가 말했듯이, 좋은 규칙은 "첫 시도부터 컨벤션에 맞는 출력으로 인해 제안 사항을 그대로 더 많이 수용하게 된다"는 의미입니다.

Cursor와 함께 다른 AI 코딩 도구를 사용하는 경우 개념이 직접적으로 전달됩니다. Claude Code는 CLAUDE.md를 사용하고, GitHub Copilot에는 지시 파일이 있으며, Windsurf에는 자체 형식이 있지만 기본 원칙은 동일합니다.

규칙 우선순위 작동 방식

여러 규칙이 동일한 파일에 적용될 때 Cursor는 명확한 계층 구조를 따릅니다:

팀 규칙은 Team 및 Enterprise 플랜에서 사용할 수 있습니다. 관리자가 Cursor 대시보드에서 설정하며 조직 전체에서 강제되며, 개별 개발자는 이를 끄지 못합니다.

프로젝트 규칙 내에서 두 규칙이 동일한 파일에 적용되고 충돌하는 경우 동작은 엄격하게 정의되지 않았습니다. 실제로 나중에 로드된 규칙이 우선순위를 갖는 경향이 있습니다. 파일에 번호를 붙이면(001-base.mdc, 002-components.mdc) 예측 가능한 순서를 얻을 수 있습니다.

일반적인 실수와 해결 방법

수십 개의 커뮤니티 스레드를 읽고 프로젝트 전반에 걸쳐 규칙을 테스트한 결과, 사람들을 가장 많이 곤란하게 하는 실수는 다음과 같습니다:

너무 모호한 규칙 작성. "깨끗한 코드를 작성하세요"는 AI에게 아무것도 알려주지 않습니다. "기본 exports가 아닌 named exports를 사용하세요. 컴포넌트를 imports, types, function, sub-components 순서로 구조화하세요"라고 하면 실행 가능한 정보를 제공합니다.

모든 것을 항상 적용으로 만들기. 첫 번째 본능은 모든 규칙에 alwaysApply: true를 설정하는 것입니다. 저항하세요. 규칙을 분기별로 감사하세요. 항상 켜져 있는 규칙이 2-3개 이상이라면 아마도 토큰을 낭비하고 있을 것입니다.

규칙 테스트 잊기. 규칙을 작성한 후 관련 파일을 열고 규칙을 따라야 하는 무언가를 생성하도록 Cursor에 요청하세요. 그렇지 않다면 글롭 패턴이 잘못되었거나 지시가 충분히 명확하지 않을 수 있습니다.

안티패턴 문서화 무시. AI에게 무엇을 해야 하는지 말하는 것은 일의 절반입니다. 무엇을 하지 않아야 하는지 말하는 것이 나머지 절반입니다. 각 규칙에 잘못된 접근 방식의 명시적인 예제가 포함된 "절대 하지 말 것" 섹션을 포함하세요.

UI의 규칙 저장 무시. 알려진 버그로 인해 규칙 편집 내용이 사라질 수 있습니다. 변경 사항이 사라지면 Cursor를 완전히 닫고, 저장되지 않은 변경 사항 팝업에서 "재정의(Override)"를 선택한 후 다시 엽니다.

Cursor Rules vs CLAUDE.md vs AGENTS.md

Cursor만이 지시 파일을 사용하는 도구는 아닙니다. 여러 AI 코딩 어시스턴트를 사용하는 사람을 위한 형식 비교입니다:

Cursor의 장점은 세분화입니다. CLAUDE.md와 AGENTS.md는 더 간단하며 모든 것을 항상 로드합니다. Cursor는 적절한 시기에 올바른 규칙을 로드할 수 있게 해주며, 이는 지시 사항 세트가 수백 줄을 넘어갈 때 중요해집니다.

이러한 도구 전반에 걸쳐 컨텍스트가 AI 출력에 어떻게 영향을 미치는지에 대한 자세한 내용은, 사용하는 에디터와 관계없이 적용되는 원칙을 분석한 컨텍스트 엔지니어링 가이드를 참조하세요.

FAQ

.cursorrules는 폐기되었나요?

예. 프로젝트 루트의 단일 .cursorrules 파일은 여전히 작동하지만, Cursor는 .cursor/rules/*.mdc 파일로의 마이그레이션을 권장합니다. 새 형식은 글롭 패턴, 조건부 로드 및 더 나은 조직화를 지원합니다. 모놀리식 파일을 집중화된 규칙으로 분할하여 마이그레이션하세요.

어떤 파일 확장자를 사용해야 하나요, .mdc인가요 .md인가요?

YAML 프론트매터(description, globs, alwaysApply)를 포함하는 파일에는 .mdc를 사용하세요. 일반 .md 파일도 rules 디렉토리에서 작동하지만 조건부 로드를 가능하게 하는 프론트매터 메타데이터를 지원하지 않습니다.

프로젝트에 몇 개의 규칙이 있어야 하나요?

대부분의 프로젝트에는 58개가 적당합니다. 항상 켜져 있는 기본 규칙 1개, 파일 유형별로 범위가 지정된 자동 첨부 규칙 34개, 특수 작업을 위한 수동 규칙 1~2개입니다. 규칙이 10개 이상이면 일부는 통합하거나 제거할 수 있다는 의미입니다.

Cursor 규칙이 자동 완성 및 탭 완성에 영향을 미치나요?

규칙은 채팅 및 에이전트 상호작용에 적용됩니다. 사용자 규칙은 인라인 편집(Cmd/Ctrl+K)에 적용되지 않으며, 규칙은 일반적으로 Cursor Tab 자동 완성 제안에 영향을 미치지 않습니다. 채팅 및 Composer 세션에서 가장 효과적입니다.

여러 프로젝트 간에 규칙을 공유할 수 있나요?

예, Cursor의 Remote Rules 기능을 통해 가능합니다. Cursor Settings > Rules, Commands로 이동하여 "Remote Rule (GitHub)"을 선택하고 저장소 URL을 붙여넣으세요. 소스 저장소가 업데이트되면 규칙이 자동으로 동기화됩니다. 또는 공유 규칙 저장소를 유지하고 각 프로젝트에 심볼릭 링크를 걸 수 있습니다.

권장되는 최대 규칙 길이는 얼마인가요?

Cursor 문서는 개별 규칙을 500줄 미만으로 유지할 것을 권장합니다. 실제로는 규칙당 100줄 미만을 목표로 하세요. 짧은 규칙은 유지 관리가 쉽고 토큰 비용이 적게 듭니다. 규칙이 150줄을 초과하면 두 개의 집중된 규칙으로 분할하세요.

규칙이 Cursor의 모든 AI 모델에서 작동하나요?

규칙은 Cursor가 지원하는 모든 모델(Claude, GPT-4o, Gemini 등)에서 작동합니다. 규칙은 선택한 모델과 관계없이 시스템 수준 컨텍스트로 주입됩니다. 모델 동작은 다를 수 있지만 규칙 자체는 모델에 독립적입니다.

작동하지 않는 규칙을 어떻게 디버깅하나요?

첫째, 글롭 패턴이 파일과 일치하는지 확인하세요. 파일을 열고 규칙이 컨텍스트 패널에 나타나는지 확인하세요. 둘째, 규칙을 트리거해야 하는 직접적인 질문으로 테스트하세요. 셋째, 규칙 내용 자체가 작동하는지 확인하기 위해 일시적으로 alwaysApply: true를 설정해 보세요. 작동한다면 문제는 글롭 패턴에 있습니다.

.cursor/rules를 git에 커밋해야 하나요?

물론입니다. 프로젝트 규칙의 전체 목적은 팀 전체의 일관성입니다. 개인 선호 파일을 제외하고 .cursor/rules/의 모든 것을 커밋하세요. everyone에게 적용되지 않아야 하는 개별 설정을 위해 personal.mdc를 .gitignore에 추가하세요.

Cursor 규칙을 MCP 서버와 함께 사용할 수 있나요?

예, 그리고 서로 잘 보완합니다. 규칙은 AI가 코드를 작성해야 하는 방식을 정의하는 반면, MCP 서버는 AI에게 외부 도구와 데이터에 대한 액세스 권한을 부여합니다. 규칙은 "항상 내부 API 클라이언트를 사용하세요"라고 말할 수 있고, MCP 서버는 개발 중에 AI가 실제로 해당 API를 쿼리할 수 있게 해줍니다.

AI 기능이 로드맵에 있다면, 그것은 우리의 전문 분야입니다: Techsy의 AI 통합 팀은 LLM 시스템을 프로토타입에서 프로덕션으로 끌어올립니다. 스택에 대한 제2의 의견이 필요하신가요? 무료 상담받기.

출처

• Cursor Rules 문서
• Trigger.dev, 훌륭한 Cursor Rules 작성법
• Cursor 포럼, MDC Rules 모범 사례 및 문제 해결
• Peakvance, Cursor Rules 가이드: 토큰 세금
• GitHub의 awesome-cursor-rules-mdc