이런 상황에 쓰면 좋아요

Cursor를 막 쓰기 시작했을 때 가장 답답한 게, AI가 매번 우리 팀 컨벤션을 모르고 비슷한 실수를 반복한다는 점입니다. Cursor Rules는 “이 프로젝트에선 이렇게 짜라"를 한 번 적어두면 모든 채팅·편집에 자동으로 적용되는 시스템입니다. 룰을 잘 잡아두면 같은 지적을 매번 댓글로 남길 일이 사라집니다.

준비물

• Cursor 최신 버전 (2026년 4월 기준 .cursor/rules 디렉토리 방식이 권장)
• Git 저장소 (룰을 커밋해 팀 전체에 공유)
• 프로젝트의 코드 스타일 가이드(있으면 그대로 활용, 없으면 자주 받는 코드 리뷰 코멘트 5~10개를 떠올려 보세요)
• 두 가지 방식 중 선택:
  • 단일 파일 방식: 저장소 루트의 .cursorrules (마크다운)
  • 디렉토리 방식: .cursor/rules/*.mdc (글롭·자동 적용·수동 적용 등 세분화 가능)

단계별 사용법

1. 자주 발생하는 AI 실수를 5~10개 적어둡니다. “비동기 함수에 try/catch 안 넣음”, “테스트 누락”, “console.log 남김” 등 실제 발생한 실수만 적어야 룰이 살아 있습니다.
2. .cursor/rules/ 디렉토리를 만듭니다. 작은 프로젝트라면 단일 .cursorrules로 시작해도 무방합니다. 규모가 커지면 디렉토리 방식이 유지보수가 편합니다.
3. core.mdc 같은 항상 적용 룰을 만듭니다. 코딩 스타일·금지 사항·실행 명령 같은 “프로젝트 전역” 규칙을 한 파일에 모읍니다. 합쳐서 500줄을 넘지 않게 유지합니다.
4. 글롭 스코프 룰을 분리합니다. 예: frontend.mdc는 globs: ["src/web/**/*.tsx"]로 적용 범위를 좁힙니다. 백엔드·인프라처럼 영역이 다른 룰은 한 덩어리로 묶지 않습니다.
5. 룰 안에서는 짧고 직접적으로 씁니다. “Always run pnpm test before declaring done.” 같은 식. 같은 의미를 두 줄로 적지 마세요.
6. 파일 본문을 룰에 복사하지 말고 참조하세요. 큰 파일을 통째로 복붙하면 룰이 빨리 낡습니다. “see docs/conventions.md“라고 가리키는 편이 안전합니다.
7. 변경된 룰은 git에 커밋합니다. 팀원 모두가 같은 AI 보조를 받게 됩니다.

결과 예시

.cursor/rules/core.mdc의 실전 예입니다.

---
description: Project-wide coding rules. Always apply.
alwaysApply: true
---

# 우리 팀 룰

## 일반
- TypeScript strict 모드 가정. `any` 금지.
- 함수는 한 가지 일만. 30줄 넘으면 분리.
- 변경 후 반드시 `pnpm test`와 `pnpm lint` 실행.

## 금지
- console.log를 커밋 코드에 남기지 말 것 (디버그용은 logger 사용).
- 새로운 라이브러리 추가는 PR 설명에 이유를 적을 것.
- TODO 주석 남기지 말 것 — 이슈로 변환.

## 명령
- 테스트: `pnpm test --run`
- 타입체크: `pnpm typecheck`
- 데모 실행: `pnpm dev`

.cursor/rules/frontend.mdc처럼 글롭으로 좁히면 더 효과적입니다.

---
description: 프론트엔드 React 룰
globs: ["apps/web/**/*.tsx", "apps/web/**/*.ts"]
---

- 컴포넌트는 함수형, default export 금지.
- 상태 관리는 Zustand. Redux 추가 금지.
- 데이터 페칭은 TanStack Query 훅으로만.
- Tailwind 클래스 외 CSS-in-JS 금지.

자주 발생하는 문제

• 룰이 길어질수록 무시당해요. → 한 파일 500줄 이내로 유지하고, 도메인별로 쪼개세요. 한 덩어리로 키우는 순간 효과가 급격히 떨어집니다.
• 룰을 다 적었는데도 같은 실수를 반복해요. → 룰을 추상적으로 적었을 가능성이 큽니다. “잘 짜라” 대신 “함수에 인자가 4개를 넘으면 객체로 묶어라"처럼 행동 단위로 쓰세요.
• .cursorrules와 .cursor/rules/ 둘 다 있어요. → 둘 다 동작하지만 동작 방식이 다릅니다. 점진적으로 디렉토리 방식으로 옮기고, 옮긴 항목은 .cursorrules에서 제거해 중복을 줄이세요.
• 개인 룰과 팀 룰이 섞여요. → 팀 룰만 git에 커밋하고, 개인 취향 룰은 .cursor/rules/에 두지 말고 사용자 설정으로 분리하세요.

더 효율적으로 쓰는 팁

1. 새 룰은 “같은 코드리뷰 댓글을 두 번 남길 때” 추가하세요. 미리 너무 많이 쓰면 죽은 룰만 쌓입니다.
2. 명령어 섹션을 따로 두세요. 테스트·빌드·실행 명령을 룰 한 섹션에 몰아두면 AI가 “끝내기 전에 이걸 돌리세요"를 잘 따라 합니다.
3. PR 템플릿과 룰을 함께 가다듬으세요. PR 체크리스트에 들어갈 만한 항목이 곧 룰 후보입니다.
4. 룰 위반 사례를 예시로 적어두세요. “이렇게 짜지 마라(예) → 이렇게 짜라(예)” 한 줄 짝이 의외로 강력합니다.
5. 다른 팀의 룰을 그대로 가져오지 마세요. 인터넷에 공유된 .cursorrules는 영감 정도만 얻고, 우리 코드에서 실제 발생한 실수 기반으로 다듬는 게 정답입니다.

마치며

자주 발생하는 실수 5개로 시작 → core.mdc 한 파일 → 영역별 글롭 룰. 이 순서대로 쌓으면 Cursor가 우리 팀 코드 스타일을 점점 더 잘 따라 합니다. AI에게 컨텍스트를 잘 넘기는 더 일반적인 패턴은 Claude로 텍스트에서 표 데이터 깔끔하게 뽑아내기에서 “스키마 먼저 정의” 흐름을, 보고서·요구사항 문서를 다루는 작업은 Claude로 PDF 30페이지를 5분 안에 요약하는 법을 함께 읽어 보세요.