Cursor Rules 고급 설정: 나만의 AI 코딩 어시스턴트 만들기
같은 프로젝트에서도 Cursor가 때로는 깔끔한 스타일의 코드를 생성하지만, 때로는 익숙한 방식과 전혀 맞지 않는 코드를 내놓습니다. .cursorrules에 규칙을 잔뜩 적어 놓았는데도 AI는 마치 ‘보지 못한’ 것처럼 행동합니다. 프로젝트를 바꿀 때마다 다시 설정해야 하기도 합니다.
저도 처음 Cursor Rules를 쓸 때 이런 문제를 겪었습니다. 몇 시간이나 들여 규칙을 작성했지만 AI가 생성하는 코드는 여전히 그대로였습니다. 나중에야 문제는 규칙 자체가 아니라 이 시스템을 완전히 잘못 이해한 데 있다는 것을 알게 되었습니다.
이 글에서는 Cursor Rules를 고급 수준으로 활용하는 방법을 다룹니다. 단순히 ‘.cursorrules란 무엇인가’를 설명하는 입문 글이 아니라, 이 도구를 실제로 제대로 활용하는 데 도움이 되는 실전 경험을 소개합니다.
1. Cursor Rules 핵심 개념 다시 이해하기
1.1 .cursorrules에서 .cursor/rules로: 규칙 시스템의 발전
Cursor를 어느 정도 사용했다면 아직 기존의 .cursorrules 단일 파일을 쓰고 있을 수 있습니다. 이 방식도 분명 작동하지만 솔직히 한계가 뚜렷합니다.
단일 파일의 문제는 무엇일까요? 첫째, 모든 규칙이 한 파일에 몰려 있어 유지 관리가 어렵습니다. 둘째, 서로 다른 파일 유형에 각기 다른 규칙을 지정할 수 없습니다. 예를 들어 프로젝트에 React 컴포넌트와 Python 스크립트가 모두 있는데 규칙을 나눠 작성하고 싶어도 단일 파일로는 할 수 없습니다.
2026년 Cursor는 MDC 형식과 함께 새로운 .cursor/rules/ 디렉터리 구조를 출시했고, 이 문제들은 대부분 해결되었습니다.
새 디렉터리 구조는 다음과 같습니다.
.cursor/
└── rules/
├── base.mdc # 기본 규칙
├── frontend.mdc # 프론트엔드 규칙
├── backend.mdc # 백엔드 규칙
└── testing.mdc # 테스트 규칙각 파일은 독립적인 규칙 모듈이며 glob 패턴으로 적용 범위를 지정할 수 있습니다. 예를 들어 frontend.mdc는 .tsx 파일에만, backend.mdc는 .py 파일에만 적용되도록 설정할 수 있습니다.
마이그레이션도 어렵지 않습니다. 기존 프로젝트의 .cursorrules도 계속 사용할 수 있고, 새 프로젝트는 새 형식을 바로 쓰면 됩니다. 기존 프로젝트를 업그레이드하려면 단일 파일을 여러 .mdc 파일로 나누기만 하면 됩니다. 하위 호환을 지원하므로 문제가 생길까 걱정하지 않아도 됩니다.
1.2 세 가지 규칙 유형의 올바른 사용 사례
Cursor의 규칙 시스템은 세 가지 유형으로 나뉘는데, 이들의 관계를 혼동하는 사람이 많습니다.
**Project Rules(프로젝트 규칙)**는 .cursor/rules/ 디렉터리에 두며 현재 프로젝트에만 적용됩니다. React 18 + Tailwind를 사용한다는 식으로 프로젝트 고유의 내용을 작성하기에 적합합니다. 다른 팀원이 프로젝트를 clone하면 이 규칙도 자동으로 사용할 수 있습니다.
**Team Rules(팀 규칙)**는 클라우드에 저장되고 팀원들이 공유합니다. ‘모든 컴포넌트는 named export를 사용한다’, ‘API 응답 형식을 통일한다’ 같은 팀 코딩 규칙을 두기에 적합합니다. 이 기능은 Cursor의 Team 버전이 필요합니다.
**User Rules(사용자 규칙)**는 Cursor 설정에서 구성하며 모든 프로젝트에 적용됩니다. Tab 들여쓰기와 공백 중 무엇을 선호하는지, 주석을 한국어로 쓸지 영어로 쓸지 같은 개인 설정에 적합합니다.
우선순위는 User Rules가 가장 높고, 그다음이 Team Rules, 마지막이 Project Rules입니다. 즉, User Rules에 ‘공백으로 들여쓰기’라고 적고 Project Rules에 ‘Tab으로 들여쓰기’라고 적었다면 최종적으로 User Rules를 따릅니다.
1.3 규칙이 적용되는 내부 원리
조금 기술적인 내용이지만 이해해 두면 규칙 작성에 큰 도움이 됩니다.
AI가 요청을 처리할 때 규칙 파일의 내용을 컨텍스트의 일부로 모델에 ‘제공’합니다. 즉, 규칙도 token을 소비합니다. 따라서 규칙은 길다고 좋은 것이 아닙니다. 불필요한 말을 잔뜩 쓰면 token만 낭비하고 오히려 효과가 떨어집니다.
파일 패턴 매칭(globs)은 .gitignore와 비슷하게 작동합니다. ["**/*.tsx"]라고 쓰면 모든 tsx 파일을 매칭하고, ["app/api/**/*"]라고 쓰면 app/api 디렉터리 아래의 모든 파일을 매칭합니다.
여러 규칙이 같은 파일에 적용되면 어떻게 될까요? Cursor는 파일 이름의 사전순으로 규칙을 로드하며 먼저 로드된 규칙의 우선순위가 더 높습니다. 따라서 00-base.mdc, 01-frontend.mdc처럼 숫자 접두사로 로드 순서를 제어할 수 있습니다.
2. 실전 설정: 처음부터 완성하기
2.1 기본 설정: React + TypeScript 프로젝트
먼저 간단한 React 프로젝트부터 시작하겠습니다. 아래는 완성된 규칙 설정으로, .cursor/rules/react.mdc에 그대로 복사해 사용할 수 있습니다.
---
description: React + TypeScript 프로젝트 규칙
globs: ["**/*.{ts,tsx}"]
---
# 기술 스택
- React 18+
- TypeScript 5.0+
- Tailwind CSS
# 코드 스타일
- 함수형 컴포넌트를 사용하고 function 키워드로 선언
- TypeScript 인터페이스로 Props 정의
- 컴포넌트 파일 구조: exported component → subcomponents → helpers → types
- named export를 사용하고 default export는 피하기
# React 모범 사례
- Next.js를 사용한다면 Server Components 우선 사용
- 상태 관리에는 useState와 useReducer 사용
- 사이드 이펙트에는 useEffect를 사용하고 cleanup 함수 작성
- 성능에 민감한 컴포넌트는 React.memo로 최적화
# 오류 처리
- early return 패턴 우선 사용
- guard clauses로 경계 조건 처리
- 원본 오류를 그대로 던지지 말고 사용자 친화적인 오류 메시지 제공이 규칙의 구조는 간단합니다. 먼저 기술 스택을 선언해 AI에 어떤 프레임워크를 쓰는지 알려 줍니다. 그다음 코드 스타일로 원하는 작성 방식을 전달하고, 마지막으로 모범 사례와 오류 처리에 관한 구체적인 지침을 제공합니다.
2.2 고급 설정: Next.js 14 풀스택 프로젝트
Next.js 프로젝트는 프론트엔드와 백엔드를 모두 다루므로 조금 더 복잡합니다. 규칙은 모듈식으로 구성하는 것을 권장합니다.
.cursor/
└── rules/
├── base.mdc # 기본 규칙
├── api.mdc # API 라우트 규칙
├── components.mdc # 컴포넌트 규칙
├── database.mdc # 데이터베이스 규칙
└── testing.mdc # 테스트 규칙api.mdc 예시를 살펴보겠습니다.
---
globs: ["app/api/**/*.{ts,tsx}"]
---
# API 라우트 규칙
- Route Handlers(app/api/) 사용
- 모든 응답에 통일된 APIResponse 타입 사용
- Zod로 요청 매개변수 검증
- 오류 처리에는 next-safe-action 사용
# 응답 형식
- GET 요청: { success: boolean, data?: T, error?: string } 반환
- POST 요청: 입력 검증 → 로직 처리 → 응답 반환
- 오류 분류: 검증 오류, 비즈니스 오류, 시스템 오류를 각각 처리이렇게 하면 API 관련 규칙은 app/api/ 디렉터리 아래의 파일을 편집할 때만 적용됩니다. 컴포넌트를 작성할 때 AI가 API 관련 제안을 잔뜩 내놓는 일도 없습니다.
2.3 심화 설정: Python FastAPI 백엔드 프로젝트
백엔드를 Python으로 작성한다면 규칙의 내용도 조금 달라집니다.
---
description: Python FastAPI 프로젝트 규칙
globs: ["**/*.py"]
---
# 기술 스택
- Python 3.12+
- FastAPI 0.100+
- SQLAlchemy 2.0
- Pydantic v2
# 코드 스타일
- Black으로 코드 포맷팅
- isort로 import 정렬
- 빠뜨리지 말고 type hints 작성
- 함수 이름에는 snake_case 사용
# FastAPI 모범 사례
- 의존성 주입으로 데이터베이스 연결 관리
- Pydantic 모델로 입력 검증
- background tasks로 비동기 작업 처리
- 통합 오류 처리 미들웨어 구현
# 데이터베이스
- SQLAlchemy 2.0 비동기 API 사용
- Alembic으로 데이터베이스 마이그레이션 관리
- soft delete와 감사 로그 구현Python 프로젝트의 규칙은 스타일 도구(Black, isort)와 타입 힌트에 중점을 둡니다. 그러면 AI가 코드를 생성할 때 이러한 규칙을 자동으로 따릅니다.
2.4 팀 협업 설정: 여러 사람이 참여하는 프로젝트 관리
팀의 Tech Lead로서 코딩 스타일을 통일하고 싶다면 다음과 같이 구성할 수 있습니다.
프로젝트 루트 디렉터리/
├── .cursor/
│ └── rules/
│ ├── README.md # 규칙 사용 안내
│ ├── base.mdc # 전역 기본 규칙
│ ├── frontend.mdc # 프론트엔드 규칙
│ ├── backend.mdc # 백엔드 규칙
│ └── team-guidelines.mdc # 팀 규칙
└── .cursorrules # 하위 호환용(선택 사항)실전 팁 몇 가지를 소개합니다.
규칙을 버전 관리에 포함하세요. 그러면 팀원 누구나 프로젝트를 clone하는 것만으로 규칙을 사용할 수 있으며 별도 설정이 필요 없습니다.
각 규칙 파일에 설명 주석을 추가하세요. 새 팀원이 합류했을 때 규칙 파일을 살펴보는 것만으로 팀의 코딩 규칙을 이해할 수 있습니다.
규칙을 정기적으로 검토하고 업데이트하세요. 프로젝트가 발전하면 규칙도 함께 바뀌어야 합니다. 매 iteration마다 규칙의 효과를 되돌아보는 것을 권장합니다.
3. 디버깅과 최적화: 규칙을 실제로 적용하기
3.1 규칙 디버깅 팁
규칙을 작성했는데도 AI가 따르지 않나요? 가장 흔한 문제입니다. 제가 정리한 진단 체크리스트는 다음과 같습니다.
1. 파일 위치 확인
규칙 파일은 올바른 디렉터리에 있어야 합니다.
.cursor/rules/디렉터리 아래(권장)- 또는 프로젝트 루트 디렉터리의
.cursorrules파일
위치가 잘못되면 AI가 파일을 전혀 읽지 못합니다.
2. glob 패턴 확인
globs 설정이 잘못되면 규칙이 적용되지 않습니다. Cursor에서 파일 하나를 열고 AI에 ‘현재 로드된 규칙을 알려 주세요.’라고 직접 물어보세요. AI가 확인한 규칙을 알려 줍니다.
3. YAML 형식 확인
MDC 파일 앞부분의 frontmatter는 YAML 형식입니다. 들여쓰기가 잘못되거나 콜론을 빠뜨리면 파싱에 실패합니다.
4. 규칙 충돌 확인
여러 규칙이 서로 충돌할 수 있습니다. 같은 사항에 서로 다른 요구를 하는 규칙이 있는지 확인하고 하나로 합치면 됩니다.
3.2 규칙 최적화 전략
규칙은 많을수록 좋다고 생각하는 사람이 많습니다. 하지만 그렇지 않습니다. 규칙이 너무 길면 오히려 AI가 ‘소화하기’ 어려워집니다.
원칙 1: 간결함이 최우선
가장 중요한 규칙을 앞에 배치하세요. AI도 규칙을 처음부터 끝까지 읽기 때문에 앞부분의 내용을 더 잘 기억합니다.
원칙 2: 구체적이고 명확하게
두 가지 예시를 비교해 보겠습니다.
모호한 작성 방식:
# 코드 스타일
- 간결한 코드 작성
- 모범 사례 사용
- 성능에 주의구체적인 작성 방식:
# 코드 스타일
- 함수형 컴포넌트를 사용하고 class 컴포넌트는 피하기
- early return 패턴으로 중첩 줄이기
- 성능에 민감한 컴포넌트는 React.memo로 래핑
- 반복문 안에서 인라인 함수를 작성하지 않기두 번째 방식에서는 AI가 무엇을 해야 하는지 명확하게 알 수 있습니다. 첫 번째 방식에서는 AI가 ‘추측’할 수밖에 없습니다.
원칙 3: 계층적으로 구성하기
‘기술 스택 → 코드 스타일 → 모범 사례 → 오류 처리’ 순서로 구성하세요. 논리가 명확하면 AI도 이해하기 쉽습니다.
원칙 4: 지속적으로 개선하기
규칙은 한 번 쓰고 끝나는 것이 아닙니다. 한동안 사용해 보고 AI가 생성하는 코드의 품질이 좋아졌는지 확인한 뒤, 부족한 부분을 다시 조정하세요.
3.3 규칙 효과 평가
규칙이 효과가 있는지는 어떻게 알 수 있을까요? 다음 지표를 살펴보세요.
- 첫 시도 통과율: AI가 생성한 코드 중 바로 사용할 수 있는 비율은 얼마나 되나요?
- 스타일 일관성: 서로 다른 시점에 생성한 코드의 스타일이 일관적인가요?
- Bug 수: 규칙을 적용한 뒤 Bug가 줄었나요?
- 개발 효율: 코드를 더 빠르게 작성할 수 있나요?
이 지표를 기록하고 규칙 사용 전후의 변화를 비교하면 규칙이 실제로 도움이 되는지 알 수 있습니다.
4. 2026년 최신 실전 방식: MDC 형식과 모듈화
4.1 MDC 형식 심층 분석
MDC는 Cursor가 출시한 새 규칙 형식으로 기존 .cursorrules보다 훨씬 유연합니다.
파일 구조는 다음과 같습니다.
---
description: 규칙 설명(선택 사항)
globs: ["파일 매칭 패턴"]
alwaysApply: false(선택 사항, 기본값 false)
---
# 규칙 내용
구체적인 규칙 내용을 여기에 작성합니다...description은 사람이 읽는 항목으로, 규칙의 용도를 이해하기 쉽게 해 줍니다.
globs는 규칙을 어떤 파일에 적용할지 결정하는 파일 매칭 패턴입니다.
["**/*.tsx"]— 모든 tsx 파일 매칭["app/api/**/*"]— app/api 디렉터리 아래의 모든 파일 매칭["*.test.{ts,tsx}"]— 테스트 파일만 매칭
alwaysApply를 true로 설정하면 파일 매칭과 관계없이 규칙이 항상 적용됩니다. token을 낭비할 수 있어 일반적으로 권장하지 않습니다.
4.2 모듈식 규칙 아키텍처
대규모 프로젝트에는 더 세분화된 모듈식 구조를 권장합니다.
.cursor/
└── rules/
├── 00-base.mdc # 기본 규칙
├── 01-tech-stack.mdc # 기술 스택 선언
├── 02-code-style.mdc # 코드 스타일
├── 10-frontend/ # 프론트엔드 규칙(하위 디렉터리)
│ ├── react.mdc
│ └── tailwind.mdc
├── 20-backend/ # 백엔드 규칙(하위 디렉터리)
│ ├── api.mdc
│ └── database.mdc
└── README.md # 규칙 사용 문서숫자 접두사로 로드 순서를 제어합니다. 00-으로 시작하는 파일을 먼저 로드하고 10-으로 시작하는 파일을 나중에 로드합니다. 이렇게 하면 기본 규칙을 먼저 적용할 수 있습니다.
하위 디렉터리를 사용하면 더 세밀하게 관리할 수 있습니다. 프론트엔드 규칙은 10-frontend/에, 백엔드 규칙은 20-backend/에 두면 찾기 편합니다.
4.3 규칙 생성 도구 추천
규칙을 처음부터 작성하기 싫다면 몇 가지 커뮤니티 도구의 도움을 받을 수 있습니다.
cursor.directory — 다양한 프레임워크의 템플릿을 바로 복사할 수 있는 온라인 규칙 라이브러리입니다.
cursorrules.org — 몇 가지 질문에 답하면 규칙 파일을 자동으로 생성해 주는 대화형 규칙 생성기입니다.
awesome-cursorrules — 20개 이상의 프레임워크를 다루는 100개 이상의 템플릿이 있는 GitHub의 엄선된 규칙 모음입니다.
다만 템플릿에서 시작하더라도 프로젝트에 맞게 수정하는 것을 권장합니다. 그대로 가져다 쓰는 데 그치지 말고 규칙의 원리를 이해해야 자신에게 정말 맞는 규칙을 작성할 수 있습니다.
5. 요약 및 실행 가이드
5.1 빠른 시작 체크리스트
지금 바로 시작하고 싶다면 다음 순서대로 진행하세요.
1단계: 프로젝트 유형을 확인합니다. React인가요? Next.js인가요? Python인가요? 아니면 다른 유형인가요?
2단계: 커뮤니티 템플릿에서 비슷한 것을 선택합니다. cursor.directory나 awesome-cursorrules에서 찾을 수 있습니다.
3단계: 프로젝트 특성에 맞게 수정합니다. 기술 스택 버전을 바꾸고 개인 설정을 추가하세요.
4단계: 효과를 테스트합니다. 코드를 몇 개 작성해 보고 AI가 생성한 코드가 기대에 더 잘 맞는지 확인하세요.
5단계: 팀과 공유합니다. 효과가 좋다면 규칙을 버전 관리에 커밋해 팀 전체가 함께 사용하도록 하세요.
5.2 실수 방지 가이드
마지막으로 제가 직접 겪은 몇 가지 실수를 소개합니다.
규칙이 너무 모호함 — AI는 무엇을 원하는지 알 수 없습니다. 더 구체적으로 작성하세요.
규칙 파일이 너무 김 — 200줄 이내면 충분합니다. 너무 길면 AI가 전부 읽지 못합니다.
테스트하지 않고 사용함 — 먼저 작은 범위에서 검증하고 효과를 확인한 뒤 전체로 확대하세요.
한 번도 업데이트하지 않음 — 프로젝트가 바뀌면 규칙도 함께 바뀌어야 합니다. 정기적으로 되돌아보세요.
5.3 더 알아보기
더 자세히 알고 싶다면 다음 리소스를 참고하세요.
- Cursor 공식 문서 — 가장 권위 있는 설명
- awesome-cursorrules — 커뮤니티 엄선 규칙
- Cursor 커뮤니티 포럼 — 질문 토론과 경험 공유
지금 프로젝트를 열고 첫 번째 Cursor Rules를 설정해 보세요. 간단한 것부터 시작해 조금씩 개선하면 됩니다. AI가 갈수록 나를 더 잘 ‘이해한다’는 사실에 놀라게 될 것입니다.
고급 Cursor Rules 설정하기
프로젝트에 모듈식 Cursor Rules를 처음부터 설정해 AI 코딩 어시스턴트의 이해도를 높입니다.
⏱️ Estimated time: 30 min
- 1
Step 1: 규칙 디렉터리 구조 만들기
프로젝트 루트 디렉터리에 .cursor/rules/ 디렉터리를 만듭니다.
```bash
mkdir -p .cursor/rules
```
기존 .cursorrules에서 마이그레이션하는 경우 먼저 원본 파일을 유지하세요. 기존 형식과 새 형식은 함께 사용할 수 있습니다. - 2
Step 2: 기본 규칙 파일 만들기
base.mdc 파일을 만들고 프로젝트의 기본 규칙을 정의합니다.
```markdown
---
description: 프로젝트 기본 규칙
globs: ["**/*"]
---
# 프로젝트 정보
- 프로젝트 이름: 프로젝트 이름
- 기술 스택: 주요 기술 나열
# 공통 규칙
- 코드 스타일 핵심 사항
- 명명 규칙
- 주석 규칙
```
이 파일은 모든 파일에 적용됩니다. - 3
Step 3: 파일 유형별 전용 규칙 만들기
frontend.mdc처럼 특정 파일 유형을 위한 규칙을 만듭니다.
```markdown
---
globs: ["**/*.{ts,tsx}"]
---
# 프론트엔드 규칙
- 컴포넌트 규칙
- 상태 관리 규칙
- 스타일 규칙
```
globs는 여러 패턴을 지원합니다: `["**/*.ts", "**/*.tsx"]` - 4
Step 4: 규칙 적용 여부 테스트하기
Cursor에서 대상 파일을 연 다음 AI에 직접 질문합니다.
‘현재 로드된 규칙을 알려 주세요.’
AI가 인식한 규칙 파일을 나열합니다. 아무것도 나오지 않으면 다음을 확인하세요.
- 파일 위치가 올바른지
- glob 패턴이 현재 파일과 일치하는지
- YAML 형식에 문법 오류가 없는지 - 5
Step 5: 버전 관리에 포함하기
규칙을 Git에 커밋합니다.
```bash
git add .cursor/rules/
git commit -m "feat: add cursor rules configuration"
```
팀원이 프로젝트를 clone하면 규칙 설정도 자동으로 받게 됩니다.
FAQ
Cursor Rules 규칙 파일은 어느 디렉터리에 두어야 하나요?
.cursorrules와 .cursor/rules/는 무엇이 다른가요?
규칙이 적용되지 않는 이유는 무엇인가요?
• 파일 위치가 잘못됨 — `.cursor/rules/` 또는 루트 디렉터리의 `.cursorrules`에 있어야 합니다.
• glob 패턴이 잘못됨 — 현재 파일과 일치하지 않습니다.
• YAML frontmatter 형식에 오류가 있음
• 규칙 내용이 너무 길거나 모호해 AI가 효과적으로 이해하지 못함
Cursor에서 AI에 ‘현재 로드된 규칙을 알려 주세요.’라고 직접 물어 진단할 수 있습니다.
규칙 파일은 어느 정도 길이가 적당한가요?
User Rules, Team Rules, Project Rules의 우선순위는 어떻게 되나요?
MDC 형식에서 globs는 어떻게 작성하나요?
• `["**/*.tsx"]` — 모든 tsx 파일 매칭
• `["app/api/**/*"]` — app/api 디렉터리 아래의 모든 파일 매칭
• `["*.test.{ts,tsx}"]` — 테스트 파일만 매칭
• `["**/*.ts", "**/*.tsx"]` — 여러 파일 유형 매칭
배열 형식으로 여러 패턴을 작성할 수 있습니다.
참고할 만한 기존 규칙 템플릿이 있나요?
2분 읽기 · 게시일: 2026년 3월 20일 · 수정일: 2026년 9월 4일
Cursor 완전 가이드
검색으로 들어왔다면 같은 시리즈의 이전 글이나 다음 글로 이동하는 것이 가장 빠릅니다.
이전
Cursor Rules 완벽 가이드: AI가 규칙에 맞는 코드를 생성하게 만드는 법(실전 설정 포함)
5분 만에 Cursor Rules를 설정해 AI가 생성하는 코드를 프로젝트 규칙에 완벽히 맞추는 방법을 알아봅니다. 설정 방법, 실전 예제, 2026년 최신 기능까지 초보자도 쉽게 따라 할 수 있습니다.
18편 중 5편
다음
대규모 프로젝트에서 Cursor Agent 활용하기: 파일 누락과 잘못된 코드 수정을 막는 7가지 방법
새벽의 시행착오 끝에 정리한 실전 팁입니다. 컨텍스트 관리와 작업 분할부터 코드 리뷰까지, 대규모 프로젝트에서 Agent의 성공률을 50%에서 90%로 높이는 방법을 소개합니다.
18편 중 7편
댓글
GitHub로 로그인하여 댓글을 남기세요