.cursorrules 완전 가이드: Cursor AI 생산성 제대로 높이는 설정법 (2026)

.cursorrules 열심히 작성해서 쓰고 있다면, 지금 당장 확인할 게 있어요.

2026년 기준 Cursor Agent 모드에서 구형 .cursorrules 파일은 규칙을 아예 무시합니다. 동일한 규칙 9개를 두 형식으로 테스트했을 때 구형 .cursorrules는 0/9 준수, 신형 .mdc 방식은 9/9 준수라는 결과가 나왔어요. 열심히 써둔 규칙이 Agent 모드에선 작동 안 하고 있을 수 있습니다.

구형 .cursorrules vs 신형 .mdc — Agent 모드 준수율 비교

 

.cursorrules가 뭔지 먼저 짚고 가면

Cursor AI가 코드를 생성하기 전에 참조하는 "프로젝트 지침서"예요. 프로젝트 루트에 파일 하나 두면 새 채팅 세션마다 "우리 프로젝트는 React 18, TypeScript strict, 함수는 30줄 이내야"라고 반복 설명 안 해도 됩니다. Cursor가 알아서 읽고 적용해요.

AI 제안 수용률이 규칙 없을 때 약 30% 수준에서, 잘 작성된 규칙을 적용하면 80% 이상으로 올라간다는 데이터가 있어요. Salesforce는 20,000명 규모 도입 후 개발 속도가 30% 이상 향상됐다고 밝혔고요. 팀 차원에서 Git에 커밋해두면 신규 입사자도 처음부터 동일한 AI 경험을 받을 수 있다는 것도 장점입니다.

저도 처음엔 .cursorrules 파일 하나만 쓰고 있었는데, Agent 모드를 쓰기 시작하면서 규칙이 전혀 안 먹히는 걸 느끼고 나서야 신형으로 갈아탔어요.

 

구형 vs 신형 — 뭐가 달라졌나

2025년 중반부터 Cursor는 .cursor/rules/*.mdc 디렉터리 방식을 공식 권장 포맷으로 내놨습니다. 구형 .cursorrules는 Chat 모드에서는 여전히 동작하지만, Agent 모드에선 완전히 무시돼요.

	구형 .cursorrules	신형 .cursor/rules/*.mdc
위치	프로젝트 루트	.cursor/rules/ 하위
형식	마크다운	YAML 프론트매터 + 마크다운
Agent 모드	작동 안 함	완전 지원
활성화 방식	항상 전체 로드	4가지 모드 선택 가능
팀 공유	Git 커밋으로 가능	동일 + 더 세밀한 제어

둘이 동시에 존재할 경우 .mdc가 우선 적용됩니다. Agent 모드 쓴다면 지금 당장 마이그레이션하는 게 맞아요.

 

신형 .mdc 4가지 활성화 모드

.mdc 파일의 YAML 프론트매터에서 4가지 모드 중 하나를 고릅니다. 이게 구형과 가장 크게 다른 점이에요 — 불필요한 규칙을 매번 로드하지 않아서 토큰 낭비를 줄일 수 있습니다.

Always Apply (alwaysApply: true) — 모든 대화에서 항상 로드. 200단어 이내로 짧게 유지하는 게 좋습니다. 기술 스택 선언, 전사 코딩 표준처럼 항상 필요한 것만.

Auto Attached (glob 패턴 지정) — 특정 파일이 컨텍스트에 들어올 때만 자동 활성화. src/components/**/*.tsx 같이 지정하면 컴포넌트 파일 작업할 때만 React 규칙이 붙어요. 200~500단어 범위.

Agent Requested (description만 있고 나머지 없음) — AI가 description을 읽고 관련성 있으면 스스로 불러옵니다. Stripe, Supabase처럼 특정 도구 쓸 때 자동으로 관련 규칙이 붙는 방식.

Manual (@rule-name으로 명시 호출) — 배포 체크리스트나 코드 리뷰 기준처럼 가끔만 쓰는 규칙에 씁니다.

.mdc 4가지 활성화 모드

 

실제로 어떻게 쓰는가 — 바로 쓸 수 있는 예시

기본 Always Apply 규칙 (스택 선언)

---
description: Core project foundation
globs: []
alwaysApply: true
---

## 기술 스택
- Frontend: React 18, TypeScript 5.4, Vite 5, Tailwind CSS 3
- Backend: Node.js 20, Express 4, Prisma 5, PostgreSQL 15

## 핵심 원칙
- 함수 길이: 30줄 이내
- 파라미터: 4개 이내 (초과 시 객체로 묶기)
- 에러 처리: try/catch 없이 외부 호출 금지
- 커밋 전 반드시 사용자 확인 요청

React + TypeScript 컴포넌트 규칙

---
description: React TypeScript component standards
globs: ["src/components/**/*.tsx", "src/pages/**/*.tsx"]
alwaysApply: false
---

- 함수형 컴포넌트만 사용, React.FC<Props> 타입 명시
- 파일명: PascalCase (예: UserProfile.tsx)
- any 타입 사용 금지 → unknown 또는 구체적 타입 사용
- 재사용 로직은 custom hooks로 분리 (use 접두사)
- 서버 컴포넌트 기본, 클라이언트 컴포넌트는 "use client" 명시

여기서 핵심은 "깔끔하게 써라" 같은 모호한 지시를 쓰지 않는 거예요. "함수는 30줄 이내, 파라미터는 4개 이내"처럼 측정 가능한 기준을 써야 AI가 명확하게 따릅니다. 한국 개발팀 실무 사례에서도 이 방식이 가장 효과적이라고 나왔어요.

Agent 안전 규칙 (꼭 추가 권장)

---
description: Agent safety rules
globs: []
alwaysApply: true
---

- .env, package.json 등 설정 파일 삭제 금지 (명시적 확인 없이)
- 데이터베이스 마이그레이션은 사용자 승인 후 실행
- 보안 취약점 발견 시 즉시 중단하고 보고

Agent 모드가 강력한 만큼 실수도 강력해질 수 있거든요. 이 규칙은 짧게라도 꼭 넣는 걸 권장합니다.

권장 .cursor/rules/ 폴더 구조

 

팀에서 쓸 때 알아야 할 것

.cursor/rules/ 폴더는 반드시 Git에 커밋하세요. 팀원 모두가 동일한 AI 경험을 받고, 코드 스타일도 자연스럽게 일관됩니다. 개인 취향 설정은 .gitignore에 넣으면 됩니다.

규칙을 직접 처음부터 쓰기 부담스럽다면 awesome-cursorrules(GitHub 별 40,000+)를 참고하세요. React, Next.js, Python, Go, Flutter까지 13개 카테고리에 걸쳐 커뮤니티가 검증한 템플릿이 모여 있습니다.

몇 가지 실용 팁이 더 있어요. 규칙 파일 수정 후 반영이 안 되면 Cursor를 재시작하는 게 먼저입니다(알려진 UI 버그). .cursorrules는 Chat/Agent에만 적용되고 Tab 자동완성과 인라인 편집(Ctrl+K)에는 적용 안 돼요. Glob 패턴에서 중괄호 {src,lib}/** 문법은 Cursor에서 동작하지 않으니 주의하세요.

Rule of Three도 유용한 기준이에요 — AI에게 같은 지시를 3번 반복했다면 그건 규칙 파일에 넣어야 한다는 신호입니다.

Cursor 말고 Windsurf를 쓰는 분들도 Cascade Rules 기능이 있어요. 비슷한 개념이지만 파일 형식이 다르니 공식 문서를 확인하는 게 좋습니다.

📌 관련 글: Windsurf vs Cursor: 2026년 AI 코드 에디터, 실제로 써보니 이게 달랐다

Agent 모드를 쓰고 있다면, 지금 .cursorrules 파일이 있는지 확인하고 .cursor/rules/ 디렉터리로 옮기는 게 오늘 할 일 1번이에요.