Cursor Rules 완전 정리: .mdc 설정부터 복사해 쓰는 레시피 5개까지 (2026)

핵심 요약: Cursor Rules는 설정보다 "뭘 써넣을지"가 어렵습니다. 이 글 하나로 둘 다 끝냅니다 — 앞부분은 .cursorrules(구식) → .cursor/rules/.mdc(현재) 전환과 4가지 적용 모드(Always·Auto Attached·Agent Requested·Manual), 뒷부분은 복사해서 바로 쓰는 .mdc 레시피 5개(베이스·프론트엔드·테스트·커밋 메시지·Django)입니다. 운영 원칙은 셋 — 규칙은 5~8개, 하나당 100줄 이하, alwaysApply는 진짜 전역 관례에만(모든 요청의 토큰을 먹으므로).

이 글에서 다루는 내용: .mdc 기본 구조와 4가지 적용 모드, 레시피 5개 전문, frontmatter 필드별 용도, 흔한 실수.

왜 .cursorrules를 그만 쓰나

초창기 Cursor는 프로젝트 루트의 .cursorrules 단일 파일에 모든 규칙을 적었습니다. 지금도 하위 호환으로 읽히지만 공식적으로 deprecated예요. 문제가 둘이었습니다 — 규칙 전체가 모든 요청에 통째로 실려 컨텍스트를 낭비하고(토큰 비용), 프론트엔드·테스트 규칙이 한 파일에 뒤섞여 관리가 어려웠죠. 현재 방식인 .cursor/rules/ 폴더 + .mdc 파일은 규칙을 관심사별로 쪼개고, 필요한 상황에만 선택적으로 적용합니다.

.mdc 구조와 4가지 적용 모드

규칙은 .cursor/rules/ 아래 .mdc 파일이고, 상단 YAML frontmatter(description / globs / alwaysApply)가 언제 적용될지를 결정합니다. 네 가지 모드로 정리됩니다.

모드	설정	용도
Always	alwaysApply: true	프로젝트 전체 원칙 (짧게!)
Auto Attached	globs 지정	특정 파일 유형 규칙 (테스트·API 등)
Agent Requested	description만	AI가 필요하다고 판단할 때
Manual	@규칙이름 호출	가끔 쓰는 특수 규칙

즉 alwaysApply는 모든 대화에, globs는 해당 패턴 파일을 만질 때만, description만 있으면 AI가 관련될 때 골라 쓰고, 이름으로 @멘션하면 수동 호출입니다. 이 구분을 이해했으면 바로 레시피로 갑니다 — 복사해서 채워 넣기만 하면 됩니다.

레시피 ① 베이스 규칙 (alwaysApply, 30줄 이하)

---
description: 프로젝트 공통 관례
alwaysApply: true
---
- 응답과 주석은 한국어로
- 기존 코드 스타일을 따르고, 새 의존성 추가 전에 반드시 물어볼 것
- 변경 후 관련 테스트 실행, 실패 상태로 마무리 금지
- 파일을 새로 만들기 전에 비슷한 기존 파일이 있는지 확인

모든 요청에 실리는 규칙이므로 여기엔 "어느 파일을 만지든 참인 것"만 둡니다. 길어지기 시작하면 아래 레시피들로 쪼개는 신호입니다.

레시피 ② 프론트엔드 전용 (globs)

---
description: React 컴포넌트 관례
globs: ["**/*.tsx", "**/*.jsx"]
---
- 함수형 컴포넌트 + named export
- 스타일은 모듈 CSS 파일에 분리
- 컴포넌트는 200줄 이하, 넘으면 분리 제안
- 상태는 최소화하고 파생값은 계산으로

tsx를 만질 때만 로드되므로 Python 작업의 토큰을 낭비하지 않습니다. globs는 src/**/*.tsx(하위 폴더 포함)와 src/*.tsx(직속만)의 차이에 주의하세요.

레시피 ③ 테스트 작성 규칙

---
description: pytest 테스트 관례
globs: ["**/test_*.py", "**/tests/**"]
---
- given-when-then 주석으로 구조화
- fixture는 conftest.py의 기존 것을 먼저 탐색
- 외부 API는 반드시 mock, 실제 호출 금지
- 하나의 테스트는 하나의 동작만 검증

레시피 ④ 커밋 메시지 (수동 호출)

---
description: 커밋 메시지 작성 규칙. 커밋 메시지를 만들 때 사용
---
- 형식: type(scope): 요약 (feat/fix/refactor/test/docs)
- 요약은 50자 이내 한국어, 본문에는 "왜"를 기록
- 이슈 번호가 있으면 footer에 Refs: #N

globs도 alwaysApply도 없이 description만 둔 규칙은 필요할 때 AI가 선택하거나 @ 멘션으로 직접 불러 쓰는 용도입니다.

레시피 ⑤ Django 프로젝트 규칙

---
description: Django 앱 관례
globs: ["**/models.py", "**/views.py", "**/serializers.py"]
---
- 쿼리는 N+1 확인: 목록 조회에 select_related/prefetch_related
- 비즈니스 로직은 뷰가 아니라 서비스 함수/모델 메서드로
- 마이그레이션 파일은 직접 수정하지 말고 새로 생성
- settings 값은 django.conf.settings로만 접근

제 프로젝트에서 실효가 가장 컸던 건 N+1 줄입니다. 이 규칙을 넣기 전에는 에이전트가 만든 목록 API를 리뷰에서 번번이 고쳤는데, 넣은 뒤로는 처음부터 select_related가 붙어 나옵니다. 규칙 하나가 리뷰 코멘트 하나를 영구히 없애는 셈이라, "리뷰에서 두 번 이상 지적한 것"을 규칙으로 승격하는 습관을 권합니다.

흔한 실수 3가지

전부 alwaysApply로 만들기 — 모든 요청이 무거워지고 무관한 지시가 모델을 혼란시킵니다. 규칙 10개 이상 — 5~8개가 적정선이고, 넘으면 통합·삭제 대상이 있다는 뜻입니다. 장문 문서화 — 규칙은 지시이지 위키가 아닙니다. 100줄을 넘기면 둘로 쪼개세요. 그리고 .cursor/rules는 git에 커밋해서 팀과 공유하는 것이 기본입니다. 규칙에 담을 "좋은 지시"의 원리는 작업 명세 글과 이어집니다.

자주 묻는 질문 (FAQ)

Q. 규칙이 적용되는지 어떻게 확인하나요?

A. 채팅 컨텍스트 표시에서 로드된 규칙을 확인할 수 있습니다. 안 뜨면 globs 패턴과 파일 확장자(.mdc), 폴더 위치(.cursor/rules/)를 순서대로 점검하세요.

Q. 규칙은 몇 개가 적당한가요?

A. 베이스 1개 + globs 규칙 3~4개 + 수동 규칙 1~2개, 합계 5~8개가 실용적인 상한입니다. 그 이상이면 토큰 낭비와 지시 충돌이 늘어납니다.

Q. 하위 폴더로 정리해도 되나요?

A. 네, .cursor/rules/frontend/react.mdc처럼 하위 폴더도 인식됩니다. 영역별로 나눠 관리하면 팀 규모가 커져도 유지보수가 쉽습니다.

한눈에 보는 요약

베이스는 짧게 하나, 영역 규칙은 globs로, 가끔 쓰는 건 description만. "리뷰에서 반복 지적한 것을 규칙으로 승격"이 규칙을 살아있게 만드는 운영법입니다.

함께 보면 좋은 글

AI에게 좋은 작업 명세 쓰는 법
Cursor로 Django 프로젝트 개발하기
Cursor 요금제·사용량·절약 총정리

참고 자료

Rules 공식 문서 (Cursor Docs)