Cursor AI 개발을 하다 보면 답답할 때가 있습니다. 분명히 "우리 프로젝트는 함수형으로 짜고, any 타입 쓰지 말라"고 채팅으로 몇 번을 말했는데, 새 파일을 만들면 또 any 범벅으로 코드를 뱉어내죠. 매번 같은 잔소리를 반복하는 기분이 든다면, 문제는 AI가 멍청해서가 아니라 규칙을 넣는 자리가 틀렸기 때문일 가능성이 높습니다. 이 글에서는 Cursor AI 개발에서 코딩 규칙이 왜 자꾸 무시되는지, 그리고 예전에 쓰던 .cursorrules 대신 지금 표준이 된 규칙 파일 두 가지를 어떻게 세팅하는지 정리합니다.
왜 Cursor AI 개발에서 규칙이 계속 무시될까
가장 흔한 원인은 규칙을 채팅창에만 적어두는 것입니다. 채팅으로 준 지시는 그 대화 안에서만 유효하고, 새 대화를 열거나 에이전트가 백그라운드로 도는 순간 증발합니다. 그래서 많은 사람이 프로젝트 루트에 .cursorrules 파일을 두는 방식을 써 왔는데, 여기에 함정이 있습니다.
Cursor 공식 문서 기준으로 루트의 .cursorrules는 레거시(구형) 포맷입니다. 특히 자율적으로 여러 파일을 고치는 Agent(에이전트) 모드에서는 이 파일이 읽히지 않습니다. 채팅과 탭 자동완성에서는 참고되지만, 정작 대규모 리팩터링이나 멀티파일 편집처럼 규칙이 제일 중요한 순간에 빠져버리는 겁니다. "규칙 파일까지 만들었는데 왜 안 지키지?"의 정체가 대부분 이것입니다.
.cursor/rules와 AGENTS.md — 지금의 규칙 파일 두 가지
2026년 현재 규칙을 넣는 표준 자리는 두 곳입니다. 성격이 다르니 역할을 나눠 쓰는 게 핵심입니다.
| 구분 | .cursor/rules/*.mdc | AGENTS.md |
|---|---|---|
| 위치 | 프로젝트 내 .cursor/rules/ 폴더 |
프로젝트 루트 |
| 성격 | Cursor 전용, 조건부 적용 세밀 제어 | 도구 중립 개방형 표준 |
| 강점 | 파일 유형별·상황별로 규칙 켜고 끄기 | 한 파일로 여러 AI 도구가 공유 |
| 적합한 내용 | 프레임워크별 코딩 컨벤션, 세부 제약 | 프로젝트 개요, 빌드·테스트 명령, 브랜치 규칙 |
.cursor/rules(.mdc): 상황에 맞게 규칙을 켜고 끈다
모던 규칙은 .cursor/rules/ 폴더 안에 .mdc 확장자 파일로 둡니다. Cursor 공식 문서에 따르면 .mdc는 "설정이 붙은 마크다운"으로, 상단 YAML 프론트매터에 세 가지 필드를 넣어 언제 이 규칙이 적용될지를 제어합니다.
- description: 이 규칙이 무슨 용도인지 한 줄 설명 (AI가 필요할 때 스스로 불러오는 판단 근거)
- globs: 적용 대상 파일 패턴 (예:
**/*.tsx) - alwaysApply: 항상 불러올지 여부(true/false)
이 조합으로 활성화 방식이 네 가지로 나뉩니다. ① Always(alwaysApply: true)는 늘 로드 — 기술 스택·폴더 구조처럼 프로젝트 전반에 필요한 것. ② Auto Attached는 globs에 맞는 파일을 열거나 편집할 때만 자동 적용. ③ Agent Requested는 description을 보고 AI가 필요하다고 판단하면 끌어옴. ④ Manual은 @규칙이름으로 직접 호출. 예를 들어 리액트 컴포넌트 규칙을 globs: ["**/*.tsx"]로 걸어두면, 백엔드 파일을 만질 땐 끼어들지 않아 컨텍스트가 깔끔해집니다.
실제 파일은 이런 모양입니다. 예컨대 .cursor/rules/react.mdc를 아래처럼 두면, .tsx 파일을 편집할 때만 이 규칙이 붙습니다.
---
description: React 컴포넌트 작성 규칙
globs: ["**/*.tsx"]
alwaysApply: false
---
- 함수형 컴포넌트만 사용한다.
- any 대신 명시적 타입을 쓴다.
- 상태 로직은 커스텀 훅으로 분리한다.여기서 핵심은 globs로 범위를 좁히는 것입니다. 프론트엔드 규칙이 백엔드 파일까지 따라붙으면 불필요한 컨텍스트가 늘고, AI가 엉뚱한 규칙을 적용할 여지도 생깁니다. "이 규칙이 언제 켜져야 하는가"를 파일 패턴으로 명확히 지정해 두는 것이 요령입니다.
AGENTS.md: 여러 AI 도구가 함께 읽는 한 장
AGENTS.md는 특정 도구에 묶이지 않은 개방형 표준입니다. OpenAI에서 시작해 현재는 리눅스 재단 산하에서 관리되며, Cursor뿐 아니라 Codex·Copilot·Gemini CLI·Aider·Windsurf·Zed 등 여러 에이전트가 같은 파일을 그대로 읽습니다. 팀원마다 쓰는 AI 도구가 다르다면, 이 한 파일이 단일 기준점이 됩니다.
중요한 차이가 하나 더 있습니다. AGENTS.md는 Chat·Composer·Agent 모드를 가리지 않고 읽힙니다. 앞서 말한 .cursorrules가 에이전트 모드에서 빠지는 것과 대비되는 지점이죠. 그래서 "이 프로젝트가 뭘 하는지, 어떤 명령으로 빌드·테스트하는지, 커밋 전 무엇을 확인해야 하는지" 같은 프로젝트 공통 지식은 AGENTS.md에 두는 편이 안전합니다. 반대로 특정 프레임워크의 세부 코딩 스타일처럼 파일마다 켜고 꺼야 하는 규칙은 .cursor/rules가 더 적합하니, 둘을 경쟁 관계가 아니라 역할 분담으로 보는 게 맞습니다.
실전: 규칙이 먹히게 만드는 4단계
1단계 — 공통 지식은 AGENTS.md에
루트에 AGENTS.md를 만들고 프로젝트 개요, 주 언어·프레임워크(버전 포함), 정확한 빌드·테스트 명령, 브랜치 규칙을 적습니다. 코드 스타일은 "언어 기본값과 다른 것만" 적는 게 요령입니다. 당연한 걸 잔뜩 적으면 정작 중요한 규칙이 묻힙니다. 예컨대 "테스트는 npm test로 돌린다", "메인 브랜치에 직접 커밋하지 않는다" 같은 실행 지침이 여기 들어갑니다.
2단계 — 세부 컨벤션은 .mdc로 쪼갠다
프레임워크별·영역별로 규칙 파일을 나눕니다. 하위 폴더도 지원하므로 .cursor/rules/frontend/react.mdc, .cursor/rules/backend/api.mdc처럼 정리하면 관리가 편합니다. 각 파일은 globs로 적용 범위를 좁혀두세요.
3단계 — 손으로 안 만들어도 된다
규칙 파일을 처음부터 손으로 쓸 필요는 없습니다. 채팅에서 /create-rule로 원하는 내용을 설명하면 프론트매터까지 갖춘 파일을 .cursor/rules에 생성해 줍니다. 또는 사이드바의 Customize → Rules → Add Rule 경로로도 만들 수 있습니다.
4단계 — git에 커밋해서 팀과 공유
규칙 파일은 반드시 git에 포함시키세요. 개인 설정처럼 로컬에만 두면 팀원은 여전히 규칙 없는 AI를 쓰게 됩니다. 커밋해 두면 저장소를 받는 모두가 같은 규칙 위에서 작업하게 됩니다.
자주 하는 실수 (FAQ)
- .cursor/rules에 .md로 저장 — 프론트매터가 없는 일반
.md는 무시됩니다. 반드시.mdc확장자를 쓰세요. - 규칙 하나에 모든 걸 몰아넣기 — 수백 줄짜리 만능 규칙보다, 상황별로 쪼개 globs로 거는 편이 실제로 더 잘 지켜집니다.
- 아직 .cursorrules만 믿기 — 에이전트 모드를 쓴다면
.cursor/rules나 AGENTS.md로 옮기는 것을 권장합니다. - 규칙에 배경 설명만 잔뜩 적기 — "~하는 게 좋다"는 서술보다 "함수형만 사용한다"처럼 짧고 명령형인 문장이 더 잘 지켜집니다.
참고: 요금제는 어디에 있나
본 글 작성 시점(2026년 8월) 기준 Cursor는 무료(Hobby) 플랜과 유료 플랜(개인용 Pro 월 20달러대부터 상위 등급까지)을 함께 제공하며, 사용량 기반 과금이 섞여 있어 실제 청구액이 플랜 표시가와 다를 수 있습니다. 규칙 파일 자체는 어느 플랜에서나 쓸 수 있으니 비용 부담 없이 먼저 세팅해 볼 수 있습니다. 다만 가격·한도는 자주 바뀌므로, 결제 전에는 항상 공식 요금 안내 페이지에서 최신 정보를 확인하세요.
결론
Cursor AI 개발에서 규칙이 무시되는 대부분의 이유는 AI 성능이 아니라 규칙을 넣는 자리 때문입니다. 프로젝트 공통 지식은 도구 중립 표준인 AGENTS.md에, 파일 유형별 세부 컨벤션은 .cursor/rules의 .mdc에 나눠 담고 git에 커밋하는 것 — 이 구조 하나면 같은 잔소리를 반복할 일이 크게 줄어듭니다. 오늘 여러분 프로젝트 루트에 AGENTS.md 한 장부터 만들어 보세요.
※ 본 글은 일반 정보 제공 목적이며, 제품의 기능·가격·정책은 업데이트에 따라 달라질 수 있으니 공식 문서에서 최신 내용을 확인하시기 바랍니다.
댓글 없음:
댓글 쓰기