.cursorrules 완벽 설정 가이드: 초보자부터 전문가까지
.cursorrules는 프로젝트 루트에 두는 일반 텍스트 파일로, Cursor의 AI가 어떻게 동작할지 알려줍니다. 어떤 코딩 스타일을 따라야 하는지, 어떤 프레임워크를 사용하는지, 어떤 패턴을 피해야 하는지 등을 지정할 수 있습니다. 매번 AI와 대화할 때 주입되는 프로젝트별 시스템 프롬프트라고 생각하면 됩니다.
Cursor 포럼에서 매주 반복해서 등장하는 질문이 있습니다: ".cursorrules를 제대로 설정하려면 어떻게 해야 하나요?" 공식 문서에서는 기본적인 내용을 다루지만, 실제로 매일 사용하면서 알게 되는 세부적인 노하우가 많습니다. 이 가이드는 커뮤니티가 지금까지 파악한 내용을 정리한 것입니다.
세 가지 규칙 유형: 어떤 것이 필요한가?
포럼에서 가장 많이 혼란을 겪는 부분입니다. Cursor에는 실제로 세 가지 다른 규칙 메커니즘이 있으며, 각각 다른 목적을 가지고 있습니다. 아래에서 정리해 드리겠습니다.
Rules for AI (전역)
Settings > General > Rules for AI에서 찾을 수 있습니다. Cursor에서 여는 모든 프로젝트에 적용되는 전역 규칙입니다. 로컬 설정에 저장되며, 프로젝트 디렉토리에는 포함되지 않습니다.
적합한 경우:
- 개인적인 선호사항 ("항상 TypeScript strict mode 사용")
- 모든 프로젝트에서 따르는 보편적인 규칙
- 모델 동작 조정 ("간결하게 응답하고, 요청하지 않은 경우 설명하지 말 것")
Always use functional components with TypeScript.
Prefer named exports over default exports.
When fixing bugs, explain the root cause briefly before showing the fix.
.cursorrules (프로젝트 수준)
프로젝트 루트 디렉토리에 .cursorrules라는 이름으로 두는 파일입니다. 이는 전통적인 방식으로, 하나의 파일에 이 프로젝트 내에서 AI가 어떻게 작동해야 하는지를 설명합니다.
적합한 경우:
- 프로젝트별 기술 스택과 규칙
- 팀 공유 규칙 (git에 커밋 가능)
- 프레임워크별 패턴 (Next.js, Django, Rails 등)
.mdc 규칙 (현대적, 범위 지정)
새로운 형식입니다. .cursor/rules/ 디렉토리 안에 .mdc 파일을 배치합니다. 각 파일은 특정 파일 패턴에 적용되며, UI에서 개별 규칙을 켜고 끌 수 있습니다.
적합한 경우:
- 규칙이 적용되는 시점을 세밀하게 제어하고 싶을 때
- 다른 디렉토리에 다른 규칙이 필요한 대규모 프로젝트
- 규칙을 선택적으로 활성화/비활성화하려는 팀
.cursor/
rules/
react-components.mdc
api-endpoints.mdc
database.mdc
testing.mdc
비교표
| 기능 | Rules for AI | .cursorrules | .mdc 규칙 |
|---|---|---|---|
| 범위 | 전역 (모든 프로젝트) | 단일 프로젝트 | 단일 프로젝트 |
| 위치 | Cursor 설정 | 프로젝트 루트 | .cursor/rules/ |
| 파일 패턴 | 해당 없음 | 해당 없음 | 규칙별 범위 지정 |
| UI에서 토글 | 예 | 아니오 | 예 |
| git을 통해 공유 | 아니오 | 예 | 예 |
| 다중 파일 | 아니오 | 아니오 (단일 파일) | 예 |
| 상태 | 안정 | 안정 (레거시) | 권장 |
세 가지를 동시에 사용할 수 있습니다. Rules for AI는 개인 기준선을 설정하고, .cursorrules 또는 .mdc 파일은 프로젝트별 세부사항을 처리합니다. 충돌이 발생하면 프로젝트 수준 규칙이 우선합니다.
효과적인 .cursorrules 파일 작성하기
대부분의 튜토리얼에서는 .cursorrules를 마크다운으로 작성하라고 말합니다. 그것도 가능하지만, 포럼 사용자 razbakov가 구조화된 JSON 사용을 강력히 주장했습니다. 이유는 다음과 같습니다: LLM은 산문보다 구조화된 데이터를 더 안정적으로 파싱하므로, 규칙이 더 일관되게 따르게 됩니다.
다음은 Next.js + TypeScript 프로젝트를 위한 실제 .cursorrules 파일로, JSON 방식을 사용한 예시입니다:
{
"project": {
"name": "My SaaS App",
"stack": ["Next.js 14", "TypeScript", "Tailwind CSS", "Prisma"],
"packageManager": "pnpm"
},
"conventions": {
"naming": {
"components": "PascalCase",
"functions": "camelCase",
"files": "kebab-case",
"constants": "SCREAMING_SNAKE_CASE"
},
"imports": {
"order": ["react", "next", "lib/*", "components/*", "relative paths"],
"noCircularImports": true,
"alias": "@/ for src/"
},
"components": {
"preferFunctional": true,
"folderByFeature": true,
"colocateStyles": true
}
},
"rules": [
"Always define TypeScript interfaces for component props",
"Use 'use client' directive only when component needs interactivity or hooks",
"Prefer server components by default in Next.js app router",
"No default exports -- use named exports for everything",
"API routes go in app/api/ following REST conventions",
"Database queries use Prisma client from lib/db.ts only",
"Error handling: use try/catch with proper error types, never swallow errors",
"Environment variables must be validated with zod in env.ts"
],
"antiPatterns": [
"Never use 'any' type -- use 'unknown' and narrow with type guards",
"Never put business logic in page.tsx files",
"Never use inline styles -- use Tailwind classes or CSS modules",
"Never import from relative paths like '../../' -- use @/ alias"
]
}
일반 텍스트보다 나은 이유
규칙을 자연어 단락으로 작성하면 AI가 의미를 해석해야 합니다. 구조화된 JSON을 사용하면:
- 각 규칙이 개별적이고 모호하지 않은 지시사항이 됩니다
- AI가 규칙과 맥락 중 어떤 부분인지 추측할 필요가 없습니다
- 카테고리별로 정리되어 유지보수가 쉬워집니다
- 규칙을 추가하거나 제거해도 형식이 깨지지 않습니다
참고: 마크다운을 선호한다면 그것도 괜찮습니다. 핵심 인사이트는 산문보다 구조입니다. 마크다운에서도 긴 단락보다는 글머리 기호와 명확한 제목을 사용하세요.
마크다운 대안
JSON이 너무 경직되어 느껴진다면, "텍스트 벽" 문제를 피하면서도 잘 구조화된 마크다운 버전을 참고하세요:
# 프로젝트 규칙
## 기술 스택
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Prisma ORM
## 명명 규칙
- 컴포넌트: PascalCase (UserProfile.tsx)
- 유틸리티: camelCase (formatDate.ts)
- 상수: SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)
- 파일: kebab-case (user-profile.tsx)
## 필수 규칙
- 항상 named exports 사용
- 모든 컴포넌트에 TypeScript prop 타입 필요
- 기본적으로 서버 컴포넌트 사용, 필요한 경우에만 'use client' 추가
- `any` 타입 절대 사용 금지
- 모든 환경변수는 zod로 검증
## 파일 구조
- 컴포넌트는 src/components/[feature]/
- 훅은 src/hooks/
- API 유틸리티는 src/lib/
- 타입은 src/types/
AI가 .cursorrules를 대신 작성하게 하기
포럼 사용자 tomredman이 공유한 유용한 팁입니다: 규칙을 처음부터 작성하는 대신, Cursor의 Agent 모드를 사용하여 코드베이스를 분석하고 자동으로 생성하도록 해보세요.
방법
- Cursor의 채팅 패널을 엽니다
- Agent 모드로 전환합니다
- 다음 프롬프트를 입력합니다:
Analyze this codebase and generate a comprehensive .cursorrules file.
Look at:
- Existing files and directory structure
- Package.json dependencies
- Config files (tsconfig, eslint, prettier, etc.)
- Existing code patterns and conventions
Output a .cursorrules file that captures the actual conventions
already used in this project. Use JSON format with clear categories
for tech stack, naming conventions, coding rules, and anti-patterns.
- 출력 결과를 꼼꼼히 검토하세요. AI는 여러분도 몰랐던 패턴까지 포착할 수 있습니다
- 생성된 파일을 편집하여 부정확한 내용은 제거하고, 빠진 내용은 추가하세요
- 프로젝트 루트에
.cursorrules로 저장하세요
일관된 패턴이 확립된 오래된 프로젝트에서 가장 잘 작동합니다. 완전히 새로운 프로젝트의 경우, 규칙을 수동으로 작성하거나 템플릿에서 시작하는 것이 더 나습니다.
생성된 규칙 반복 개선하기
처음부터 완벽한 결과를 기대하지 마세요. 제가 사용하는 워크플로우는 다음과 같습니다:
- Agent 모드로 생성합니다
- Cursor에게 새 컴포넌트를 작성해 보라고 요청하여 규칙을 테스트합니다
- 규칙에서 벗어나는 부분을 기록하고, 해당 경우에 대한 명시적 규칙을 추가합니다
- 출력이 일관되게 정확해질 때까지 몇 번 반복합니다
전체 과정은 약 15-20분이 소요되며, 나중에 "이렇게 고쳐주세요, 아니 그렇게 말고..."라는 왔다갔다하는 시간을 몇 시간 절약할 수 있습니다.
커뮤니티 리소스
처음부터 시작할 필요는 없습니다. 커뮤니티에서 여러 규칙 라이브러리를 만들었습니다:
cursor.directory
cursor.directory는 프레임워크와 언어별로 정리된 .cursorrules 파일 컬렉션입니다. 포럼에서 스타터 규칙을 찾는 가장 인기 있는 리소스입니다.
cursorrules.agnt.one
cursorrules.agnt.one는 에이전트 전용 규칙에 중점을 둡니다. Agent 모드를 많이 사용한다면 확인해 볼 가치가 있습니다.
GitHub 컬렉션
GitHub에서 .cursorrules를 검색하면 수천 개의 실제 예제를 찾을 수 있습니다:
filename:.cursorrules stars:>5
언어나 프레임워크로 필터링하여 여러분의 프로젝트와 유사한 규칙을 찾아보세요.
포럼 스레드: .cursorrules 공유하기
Cursor 포럼에는 "Share your .cursorrules"라는 고정 스레드가 있으며, 사용자들이 설정과 설명을 함께 올립니다. 실제 운영 환경에서 어떤 것이 작동하는지 보기에 좋은 자료입니다.
.cursorrules 파일을 그대로 복사해서 사용하지 마세요. 항상 실제 기술 스택과 규칙에 맞게 조정하세요. React Native 규칙 파일을 Django 프로젝트에 넣으면 해가 됩니다.
흔한 함정
수십 개의 포럼 스레드를 읽은 결과, 가장 자주 등장하는 문제는 다음과 같습니다:
1. 규칙이 너무 길면 성능이 저하됩니다
규칙이 많을수록 AI 동작이 더 좋아진다는 잘못된 인식이 있습니다. 정반대입니다. Cursor는 규칙을 코드와 대화와 함께 컨텍스트 윈도우에 주입합니다. 규칙이 길어지면 실제 코드 맥락을 위한 공간이 줄어듭니다.
가능하면 2000자 이내로 유지하세요. 5000자를 넘어간다면 과감하게 줄여야 합니다.
When you are writing React components in this project, you should always make sure
to use functional components instead of class components, and you should define
your prop types using TypeScript interfaces rather than PropTypes, and you should...
- Use functional React components only
- TypeScript interfaces for all props
- Named exports, no defaults
2. 충돌하는 규칙
전역으로 설정된 Rules for AI와 프로젝트의 .cursorrules 파일이 모두 있을 때 충돌은 불가피합니다. 예를 들어:
- 전역 규칙: "2칸 들여쓰기 사용"
- 프로젝트 규칙: "4칸 들여쓰기 사용"
Cursor는 프로젝트 수준 규칙에 더 높은 우선순위를 부여하지만, 둘 다 존재할 때 AI가 여전히 혼란스러워할 수 있습니다. 해결책: 전역 규칙은 최소한으로 유지하고, 세부사항은 프로젝트 파일에 넣으세요.
3. AI가 이미 잘 아는 것을 규칙으로 지정하기
규칙 예산을 모델이 이미 잘하는 것에 낭비하지 마세요:
- Write clean, readable code # 모델이 기본적으로 잘함
- Follow best practices # 너무 모호해서 쓸모없음
- Use proper error handling # 이미 기본 동작임
- Comment your code # 종종 불필요한 노이즈
대신, 여러분의 프로젝트가 모델의 기본값과 어떻게 다른지에 집중하세요:
- Use Zod schemas for all API input validation
- All database queries go through the repository pattern
- GraphQL resolvers must have @authenticated directive
- Use pnpm workspaces for monorepo package management
4. .cursorrules를 커밋하는 것을 잊기
팀 프로젝트에서 .cursorrules 파일이 버전 관리에 없으면 혼자만 혜택을 봅니다. git에 추가하고 온보딩 과정의 일부로 만드세요.
git add .cursorrules
git commit -m "Add project AI rules for Cursor"
참고: 일부 팀은 개발자마다 선호사항이 다르다는 이유로
.cursorrules를 git에서 제외하기도 합니다. 그런 경우.cursorrules.example을 템플릿으로 사용하고.cursorrules를.gitignore에 추가하세요.
5. 규칙을 테스트하지 않기
규칙을 작성한 후 즉시 테스트하세요. Cursor에게 다음을 요청해 보세요:
- 새 컴포넌트 생성하기
- 기존 함수 리팩토링하기
- 버그 수정하기
출력이 기대와 다르면 규칙을 조정해야 합니다. 규칙이 제대로 작동하지 않는 것을 기능 개발 도중에 발견하지 마세요.
빠른 시작 체크리스트
처음으로 .cursorrules를 설정하는 경우, 최소한의 경로는 다음과 같습니다:
-
.cursorrules(단일 파일)와.mdc(다중 파일) 중 선택하기 - Agent 모드를 사용하여 코드베이스를 분석하고 초안 생성하기
- 2000자 이내로 줄이기
- 일반적인 조언이 아닌 프로젝트별 규칙에 집중하기
- Cursor가 컴포넌트나 함수를 생성하도록 하여 테스트하기
- 출력이 일관될 때까지 반복하기
- 버전 관리에 커밋하기
- 팀과 공유하기