Cursor Rules, 설정했는데 왜 안 먹힐까요?
분명히 .cursorrules 파일에 규칙을 써뒀는데 Cursor Agent가 전혀 따르지 않는다면, 파일 내용 문제가 아닙니다. 파일 형식 자체가 이미 레거시가 됐기 때문입니다. 2025년 하반기부터 .cursorrules는 Agent 모드에서 로드조차 되지 않는 것이 공식 포럼에서 실측으로 확인됐습니다.
.cursorrules가 조용히 죽은 이유
오랫동안 Cursor를 써온 사람이라면 프로젝트 루트에 .cursorrules 파일 하나 던져놓는 게 규칙 설정의 전부라고 알고 있을 겁니다. 2024년까지는 그게 맞았습니다. 그런데 2025년 Agent 모드가 메인이 되면서 상황이 완전히 달라졌습니다.
Cursor 공식 포럼에 올라온 실측 테스트(Cursor CLI 2.4.35 기준, 2026년 2월)에 따르면, .cursorrules 파일에 규칙을 넣고 Agent 모드를 9회 돌렸을 때 준수율은 0/9, 즉 0%였습니다. 같은 규칙을 .cursor/rules/test.mdc로 옮기자 9/9, 100%가 됐습니다. (출처: Cursor 공식 포럼, 2026.02.16)
규칙이 안 먹힌다고 느꼈을 때 대부분의 사람이 규칙 문장을 다듬거나 ONLY/NEVER 강조어를 추가합니다. 막상 해보면 소용없습니다. 파일 자체가 Agent에게 읽히지 않으니까요.
💡 공식 문서와 실사용 포럼 데이터를 같이 놓고 보니 이런 차이가 보였습니다 — .cursorrules는 Cursor 공식 문서에서 이미 “레거시 형식”으로 분류됐고, Cursor는 AGENTS.md를 오픈 표준 대안으로 지원한다고 Reddit에서 직접 밝혔습니다. (출처: r/cursor, 2026.01.21)
현재 시점에서 권장되는 방식은 .cursor/rules/ 폴더 아래 .mdc 파일로 관리하거나, 단순한 프로젝트라면 프로젝트 루트의 AGENTS.md 파일로 전환하는 것입니다. 두 방식 모두 Agent 모드에서 정상 작동이 확인됩니다.
.mdc 파일 구조와 4가지 타입 완전 정리
.mdc 파일은 일반 마크다운과 생김새가 비슷하지만 맨 위에 프론트매터(frontmatter)가 붙습니다. 이 프론트매터가 규칙이 언제, 어떻게 적용될지를 결정합니다. Cursor 공식 문서 기준으로 4가지 타입이 있습니다. (출처: cursor.com/docs/rules)
| 타입 | 적용 시점 | 실사용 추천 케이스 |
|---|---|---|
| Always Apply | 모든 채팅 세션 | 코드 스타일, 언어 설정, 금지 패턴 |
| Apply Intelligently | Agent가 관련성 판단 시 | 특정 모듈 패턴, 아키텍처 가이드 |
| Apply to Specific Files | glob 패턴 일치 파일 열릴 때 | 테스트 파일 규칙, API 경로 규칙 |
| Apply Manually | @규칙명 으로 직접 호출 시 | 온보딩 체크리스트, 릴리스 가이드 |
파일을 새로 만드는 방법도 두 가지입니다. 채팅창에 /create-rule을 입력하면 Agent가 프론트매터 포함 .mdc 파일을 자동 생성해 .cursor/rules/에 저장합니다. 설정 화면에서는 Cursor Settings → Rules, Commands → + Add Rule 경로로 만들 수 있습니다.
실제 .mdc 파일의 기본 구조는 아래와 같습니다.
--- description: "TypeScript 코드 스타일 규칙" globs: ["**/*.ts", "**/*.tsx"] alwaysApply: true # 코드 스타일 - 함수형 컴포넌트만 사용, 클래스 컴포넌트 금지 - export default 대신 named export 사용 - any 타입 사용 금지, unknown 으로 대체 후 타입 좁히기 - useEffect 안에서 데이터 페칭 금지
규칙 파일 하나의 권장 최대 길이는 500줄입니다. 그 이상이면 하나의 큰 파일로 유지하는 대신 역할별로 쪼개 여러 .mdc 파일로 관리하는 게 공식적으로 권장됩니다. (출처: cursor.com/docs/rules)
alwaysApply 하나로 준수율이 0%에서 100%로 바뀝니다
솔직히 말하면 이 부분을 가장 많은 사람이 놓칩니다. .mdc 파일을 만들었는데 그래도 안 먹힌다는 제보가 포럼에 쌓이는 이유가 여기 있습니다. alwaysApply 필드를 명시하지 않으면 기본값이 false처럼 동작합니다.
같은 포럼 테스트에서 alwaysApply: true를 설정한 파일은 3/3 준수, alwaysApply: false는 0/3 준수가 확인됐습니다. 파일이 존재해도 Agent는 그냥 무시합니다. (출처: Cursor 공식 포럼, 2026.02.16)
💡 공식 문서에는 “파일이 있으면 Agent가 관련성을 판단해 적용한다”고 나와 있는데, 실측에서는 명시적 alwaysApply: true 없이는 판단조차 안 하는 것으로 나왔습니다. 문서와 실제 동작 사이에 차이가 있는 부분입니다.
정리하면: 항상 적용해야 하는 코드 스타일 규칙이라면 반드시 프론트매터에 alwaysApply: true를 명시할 것. 선택적으로 적용해도 되는 규칙이라면 Apply Intelligently 타입과 함께 description을 상세히 써서 Agent가 판단할 근거를 줘야 합니다.
Team Rules가 생긴 뒤 우선순위 체계가 달라졌습니다
Cursor 1.7 업데이트 이후 Rules 적용 순서가 공식적으로 확정됐습니다. 현재 우선순위는 Team Rules → Project Rules → User Rules 순입니다. 충돌 시 앞쪽 규칙이 이깁니다. (출처: cursor.com/docs/rules)
Team/Enterprise 플랜에서 관리자가 “Enforce this rule”을 켜면 팀원 개인이 Cursor 설정에서 끄는 것 자체가 불가능합니다. 반대로 강제 설정이 아닌 Team Rule은 팀원 각자가 Cursor Settings → Rules에서 끌 수 있습니다. 개인 설정이 항상 이긴다고 생각한 사람에게는 생각보다 중요한 변화입니다.
💡 Team Rules는 폴더 구조 없이 자유 형식 텍스트로 작성되고, glob 패턴도 지원합니다. 예를 들어 **/*.py로 설정하면 Python 파일에만 적용됩니다. Project Rules처럼 파일 단위로 분리할 필요 없이 대시보드에서 바로 관리할 수 있다는 점이 핵심입니다.
개인 사이드 프로젝트라면 Team Rules는 관계 없지만, 팀 단위로 Cursor를 쓴다면 어느 쪽 규칙이 실제로 적용되는지 대시보드에서 먼저 확인해야 합니다. 내가 .mdc에 써둔 규칙이 왜 간혹 무시되는지 이유를 여기서 찾는 경우도 있습니다.
규칙이 충돌하면 AI가 멈추는 상황, 막는 방법
두 개의 .mdc 파일에 서로 반대되는 규칙이 있고 둘 다 alwaysApply: true이면 어떻게 될까요. 실측 결과 Agent는 둘 중 하나를 조용히 선택하지 않고 작업을 멈추고 어떤 규칙을 따를지 물어봤습니다. 6회 중 6회 모두요. (출처: Cursor 공식 포럼, 2026.02.16) 쉽게 말해 AI가 폭주하는 게 아니라, 판단을 포기하고 사람에게 넘깁니다.
이 동작 자체는 안전하지만, 실제 작업 흐름에서는 귀찮습니다. 규칙 파일을 여러 개 쓰고 있다면 주기적으로 내용을 교차 검토해서 모순이 없는지 확인하는 게 좋습니다. 특히 다른 팀원이 만든 규칙 파일과 내 파일 사이에서 충돌이 생기기 쉽습니다.
공식 권장 방법은 규칙 파일을 git에 커밋해 팀 전체가 공유하는 것입니다. Agent가 실수를 반복하면 그 시점에 규칙 파일을 업데이트하고, GitHub 이슈나 PR에 @cursor를 태그하면 Agent가 직접 규칙 파일을 수정하는 흐름도 가능합니다.
ONLY/NEVER 같은 강경 표현을 쓸 때도 주의가 필요합니다. “ONLY use const”라고 써두면 카운터 변수에도 const를 쓰는 버그가 2/3 확률로 나왔습니다. 예외가 없어야 하는 규칙에만 ONLY/NEVER를 쓰고, 판단이 필요한 규칙에는 “prefer” 같은 유연한 표현이 낫습니다.
실전에서 자주 터지는 함정 3가지
규칙 설정을 제대로 해뒀는데도 기대와 다른 결과가 나오는 상황이 있습니다. 포럼과 커뮤니티에서 반복적으로 보고되는 세 가지를 정리했습니다.
자주 나오는 질문
마치며
Cursor Rules는 설정만 해두면 끝나는 “한 번만 해주면 되는 일”이 아닙니다. .cursorrules에서 .mdc로의 전환, alwaysApply 명시, Team Rules 우선순위 체계까지 버전마다 동작 방식이 바뀌고 있습니다.
규칙이 안 먹힌다고 느낄 때 가장 먼저 확인해야 할 것은 파일 형식입니다. 그다음이 alwaysApply 여부고, 그다음이 충돌 여부입니다. 이 세 가지만 짚어도 대부분의 문제는 해결됩니다.
무엇보다 규칙 파일을 git에 넣어두세요. 업데이트 한 번에 설정이 날아가는 경험은 한 번으로 충분합니다.
본 포스팅 참고 자료
- ① Cursor 공식 Rules 문서 — https://cursor.com/docs/rules
- ② Cursor 공식 Changelog — https://cursor.com/changelog
- ③ Cursor 공식 포럼 — .cursorrules Agent 모드 미작동 실측 보고 (2026.02.16) — forum.cursor.com
- ④ PromptLayer Blog — Cursor Changelog 2025-2026 분석 — blog.promptlayer.com
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Cursor는 빠른 속도로 업데이트되는 서비스로, 본문의 버전·수치·경로는 2026.04.02 기준입니다. 최신 정보는 cursor.com/changelog에서 확인하세요.
댓글 남기기