Cursor Rules 작성법: .cursor/rules와 AGENTS.md로 팀 개발 규칙 표준화하기

여러 명이 같은 저장소에서 Cursor 에이전트를 쓰면, 각자 채팅으로 전달하는 설명이 달라서 생성되는 코드의 폴더 위치·에러 처리·테스트 방식이 사람마다 갈라지기 쉽다. 이 차이를 채팅이 아니라 저장소 안의 문서로 고정하는 장치가 Cursor의 규칙(Rules)이다. Cursor 공식 문서의 Rules 페이지는 규칙을 프로젝트 규칙, 사용자 규칙, 팀 규칙, 그리고 AGENTS.md로 나눠 설명한다. 이 글은 그중 팀이 Git으로 함께 관리하는 프로젝트 규칙을 중심으로 파일 구조, 적용 방식, 표준화 절차, 적용 여부 확인 방법을 순서대로 다룬다. Cursor와 다른 도구의 차이가 궁금하다면 Cursor와 GitHub Copilot 비교 글을 먼저 보면 맥락을 잡기 쉽다.

Cursor가 규칙을 읽어 오는 네 가지 위치

규칙은 저장 위치에 따라 공유 범위와 적용 대상이 다르다. 팀 표준을 만들 때는 "누구에게 강제할 규칙인가"를 먼저 정하고 위치를 고른다.

공식 문서가 밝힌 우선순위는 팀 규칙 → 프로젝트 규칙 → 사용자 규칙 순이다. 개인 취향(답변 언어, 설명 길이)은 사용자 규칙에, 저장소마다 달라지는 코드 규칙은 프로젝트 규칙에, 회사 전체 보안 정책처럼 모든 저장소에 강제할 내용은 팀 규칙에 두면 충돌이 줄어든다. 참고로 .cursor/rules 폴더 안의 일반 .md 파일은 확장자가 .mdc이거나 이름이 AGENTS.md가 아니면 무시된다고 문서에 적혀 있으므로, 확장자를 잘못 붙이면 규칙이 조용히 빠진다.

.mdc 규칙 파일의 frontmatter와 네 가지 적용 방식

프로젝트 규칙 파일은 맨 위 frontmatter에 description, globs, alwaysApply 세 속성을 두고, 그 아래에 마크다운으로 지침을 쓴다. 다음은 프론트엔드 컴포넌트 폴더에만 적용되는 규칙의 예다.

---
description: React 컴포넌트 작성 규칙 (src/components 아래 파일 작업 시)
globs: src/components/**/*.tsx
alwaysApply: false
---

- 공용 UI는 src/components/ui, 기능 전용 컴포넌트는 src/features/<기능>/components에 둔다.
- props 타입은 같은 파일 상단에 type Props로 선언하고 default export를 쓰지 않는다.
- 데이터 요청은 컴포넌트 안에서 직접 fetch하지 않고 src/lib/api의 함수를 호출한다.
- 스타일 예시는 @src/components/ui/Button.tsx 를 따른다.

세 속성을 어떻게 조합하느냐에 따라 규칙이 붙는 시점이 달라진다.

항상 적용 규칙은 모든 대화의 컨텍스트를 차지하므로 짧게 유지한다. 나머지는 파일 패턴이나 설명 기반 적용으로 돌리면 작업과 무관한 규칙이 끼어드는 일이 줄어든다.

팀 공통 규칙을 네 단계로 표준화하기

1. 반복 지적 목록 모으기: 최근 PR 리뷰 코멘트에서 AI가 만든 코드에 반복해서 달린 지적(파일 위치, 금지 라이브러리, 누락된 테스트)을 추린다. 이 목록이 규칙의 1차 후보다.
2. 범위별로 파일 나누기: 모든 작업에 필요한 내용은 core.mdc(항상 적용), 폴더별 내용은 frontend.mdc·api.mdc(globs 지정)처럼 나눈다. 공식 문서는 규칙 하나를 500줄 이하로 유지하고 큰 규칙은 여러 개로 쪼개라고 권한다.
3. PR로 합의하기: 규칙 파일도 코드처럼 PR로 올려 리뷰를 받는다. 규칙끼리 충돌하는지(예: "모든 변경에 테스트 추가"와 "작은 변경은 테스트 생략")를 이 단계에서 걸러낸다.
4. 정기적으로 정비하기: 폴더 구조나 프레임워크 버전이 바뀌는 PR에서는 관련 규칙 파일도 함께 고치도록 PR 템플릿에 확인 항목을 넣는다.

정리된 저장소 구조는 대략 다음과 같다.

.cursor/
  rules/
    core.mdc          # alwaysApply: true — 스택, 금지 라이브러리, 검증 명령
    frontend.mdc      # globs: src/components/**/*.tsx
    api.mdc           # globs: src/app/api/**/*.ts
    release-notes.mdc # 수동 호출(@release-notes)
AGENTS.md           # 도구와 무관하게 공유할 짧은 프로젝트 안내

새 규칙은 에이전트 채팅에서 /create-rule을 입력하거나 Customize 사이드바의 Rules → Add Rule로 만들 수 있다. 같은 저장소를 Claude Code 같은 다른 도구로도 다룬다면 공통 내용은 AGENTS.md에 두고, 도구별 설정은 각 도구의 위치에 나누는 방식이 관리하기 쉽다. Claude Code 쪽 설정 위치는 Claude Code 설정과 토큰 최적화 글에서 다뤘다.

지켜지는 규칙 문장과 무시되는 규칙 문장

공식 문서는 스타일 가이드 전체를 복사하거나, 자주 쓰는 명령을 나열하거나, 코드베이스 문서를 중복해서 넣지 말고 필요한 파일을 참조하라고 안내한다. 실제로 작성할 때는 아래처럼 판단 기준이 드러나는 문장으로 바꾼다.

금지 규칙을 쓸 때는 대체 방법을 같은 줄에 적는다. "moment 금지"만 있으면 에이전트가 다른 임의의 라이브러리를 고를 수 있기 때문이다. AI가 만든 코드를 리뷰 단계에서 어떻게 거를지는 AI 생성 코드 리뷰 규칙 글과 함께 맞춰 두면 규칙과 리뷰 기준이 어긋나지 않는다.

루트 .cursorrules 파일을 .cursor/rules로 옮기는 절차

예전 방식으로 저장소 루트에 .cursorrules 한 파일만 두고 있다면, 공식 문서가 안내하는 현재 구조인 .cursor/rules로 옮겨야 범위별 적용을 쓸 수 있다.

1. 기존 .cursorrules 내용을 "모든 작업 공통", "특정 폴더 전용", "가끔만 필요" 세 묶음으로 나눈다.
2. 공통 묶음은 core.mdc에 alwaysApply: true로, 폴더 전용 묶음은 globs를 지정한 파일로, 나머지는 수동 호출 규칙으로 옮긴다.
3. 옮긴 뒤 기존 파일을 지우는 커밋을 별도로 만들어, 문제가 생기면 그 커밋만 되돌릴 수 있게 한다.
4. 팀 채널에 바뀐 위치와 파일 이름을 공지하고, 각자 로컬에 남아 있는 개인 규칙과 겹치는 내용은 사용자 규칙에서 지우도록 안내한다.

규칙이 실제로 적용되는지 확인하는 방법

• 파일 패턴 확인: globs 규칙은 해당 패턴과 일치하는 파일을 다룰 때 붙는다. 패턴에 맞는 파일을 열고 작은 수정(예: 새 컴포넌트 하나 추가)을 요청해 파일 위치와 export 방식이 규칙대로 나오는지 본다.
• 항상 적용 규칙 확인: 규칙에 적은 금지 라이브러리를 일부러 요청에 섞어 보고, 에이전트가 대체 라이브러리를 제안하는지 확인한다.
• 확장자 점검: .cursor/rules 아래에 .mdc가 아닌 .md 파일이 섞여 있지 않은지 확인한다.
• 길이 점검: 항상 적용 규칙이 길어졌다면 폴더 전용 규칙이나 수동 호출 규칙으로 내려보낸다.

규칙이 지켜지지 않을 때는 모델을 탓하기 전에 규칙 문장이 판단 기준을 담고 있는지, 다른 규칙과 충돌하지 않는지부터 확인한다. 규칙을 고치면 같은 요청을 다시 보내 결과가 바뀌는지 비교해 두면, 어떤 문장이 효과가 있었는지 팀이 함께 볼 수 있다.