.cursor/rules/: 당신의 코딩 컨벤션을 AI에게 가르치기

좋은 Agent는 기억력이 아니라 규칙으로 만든다

Cursor를 쓰다 보면 같은 말을 반복하게 된다.

"pnpm을 써." "새 패키지는 마음대로 설치하지 마." "API 호출은 fetch를 직접 쓰지 말고 기존 클라이언트를 써." "테스트 없이 리팩터링하지 마." "이 프로젝트는 App Router 구조야."

처음에는 이런 지시를 채팅창에 매번 적어도 괜찮다. 하지만 프로젝트가 커지고 Agent에게 맡기는 일이 늘어나면 반복 지시는 금방 비용이 된다. 더 큰 문제는 빠뜨리는 순간이다. 어느 날은 테스트 명령을 알려 줬고, 어느 날은 안 알려 줬다. 어느 날은 인증 패턴을 설명했고, 어느 날은 생략했다. 그러면 Agent는 코드베이스를 추측으로 채운다.

.cursor/rules/는 이 반복을 줄이기 위한 장치다. 프로젝트의 코딩 관례, 아키텍처 결정, 금지 패턴, 실행 명령어를 파일로 저장해 Agent가 작업 중 참고하게 만든다. 즉, 매번 말로 설명하던 "우리 프로젝트는 이렇게 일한다"를 저장소 안의 매뉴얼로 바꾸는 것이다.

핵심은 간단하다. 자주 반복하는 지시는 채팅이 아니라 규칙으로 옮긴다. Agent가 같은 실수를 두 번 하면 규칙을 추가한다. PR 리뷰에서 같은 지적이 반복되면 규칙을 고친다.

AI 생성 이미지

어떤 규칙을 어디에 둘 것인가

Cursor에서 규칙을 관리할 때 먼저 나눠야 할 것은 "누구에게 적용되는가"다.

User Rules

User Rules는 개인에게 적용되는 전역 규칙이다. 모든 프로젝트에서 유지하고 싶은 개인 취향을 둔다.

예를 들면 다음과 같다.

• 응답은 한국어로 한다.

• 변경 전후를 요약한다.

• 모호한 요구사항은 먼저 질문한다.

• 큰 변경은 Plan Mode로 계획을 먼저 제시한다.

개인 작업 습관에 가깝다면 User Rules에 둔다. 특정 저장소의 폴더 구조나 테스트 명령어를 User Rules에 넣으면 다른 프로젝트에서 오히려 방해가 된다.

Project Rules: .cursor/rules/*.mdc

Project Rules는 현재 저장소에 적용되는 규칙이다. 이 장의 핵심이다. 저장소 루트에 .cursor/rules/ 폴더를 만들고, 그 안에 .mdc 파일을 나누어 둔다.

여기에는 프로젝트별 사실을 적는다.

• 패키지 매니저: pnpm

• 개발 서버 명령: pnpm dev

• 테스트 명령: pnpm test, pnpm test:e2e

• 폴더 구조: src/features/*, src/shared/*

• API 호출 방식: src/lib/api/client.ts 사용

• 상태 관리 방식: 서버 상태는 React Query, 로컬 UI 상태는 Zustand

• 금지 사항: 직접 localStorage에 토큰 저장 금지

• 검증 기준: 변경 후 pnpm lint와 관련 테스트 실행

Agent가 코드의 모양을 바꾸는 데 직접 영향을 주는 정보는 Project Rules에 둔다. 저장소와 함께 버전 관리하면 좋다. 나중에 프로젝트를 다시 열었을 때도 같은 기준으로 작업할 수 있다.

Team Rules와 AGENTS.md

Team Rules는 팀이나 조직 단위의 공통 정책에 적합하다. 예를 들어 보안, 개인정보, 리뷰 기준, 배포 승인 절차처럼 여러 저장소에 걸쳐 지켜야 하는 원칙이다.

AGENTS.md는 Cursor만을 위한 파일이라기보다 여러 AI 코딩 도구가 함께 읽을 수 있는 공통 작업 지침으로 볼 수 있다. 저장소의 큰 원칙, 작업 방식, 테스트 기준을 도구 중립적으로 남기고 싶다면 AGENTS.md가 유용하다.

실무에서는 이렇게 나누면 편하다.

• 개인 말투와 작업 선호: User Rules

• 저장소의 구조, 명령어, 구현 패턴: .cursor/rules/*.mdc

• 조직 보안 정책과 리뷰 기준: Team Rules 또는 AGENTS.md

• 여러 AI 도구가 공통으로 따라야 할 기본 지침: AGENTS.md

legacy .cursorrules

예전에는 루트의 .cursorrules 파일 하나에 모든 규칙을 넣는 방식이 많이 쓰였다. 작은 프로젝트에서는 아직도 동작할 수 있지만, 규칙이 길어질수록 문제가 생긴다. 테스트, 보안, UI, API, 문서화 규칙이 한 파일에 섞이면 Agent도 필요한 정보를 찾기 어렵고 사람도 갱신하기 어렵다.

기존 .cursorrules가 있다면 한 번에 버리지 말고 나누어 옮긴다.

.cursor/rules/
  general.mdc
  testing.mdc
  security.mdc
  api.mdc
  ui.mdc

규칙 파일은 길수록 좋은 것이 아니다. 필요한 순간에 정확히 붙는 것이 좋다.

규칙의 네 가지 성격: Always, Auto Attached, Agent Requested, Manual

Cursor Rules를 설계할 때는 모든 규칙을 항상 적용하려고 하지 말아야 한다. 컨텍스트에는 비용이 있다. Agent에게 불필요한 규칙을 많이 주면 중요한 정보가 묻힌다.

규칙은 대략 네 가지 성격으로 나눌 수 있다. 프레임워크나 언어 전반에 항상 필요한 지침은 Always로, 특정 파일 패턴에만 필요한 규칙은 Auto Attached로, 사용자 의도에 따라 불러야 하는 지식은 Agent Requested로, 드물게 필요한 긴 절차는 Manual로 분리하는 방식이 권장된다.¹

Always: 항상 필요한 최소 원칙

Always 규칙에는 모든 작업에 적용되어도 방해되지 않는 최소 원칙만 넣는다.

예를 들면 다음 정도다.

• 기존 패턴을 먼저 확인한다.

• 요청 범위 밖 리팩터링을 하지 않는다.

• 새 의존성은 사용자 승인 없이 추가하지 않는다.

• 변경 후 관련 테스트 또는 타입체크 방법을 제안한다.

• 비밀 키, 토큰, 개인정보를 코드에 하드코딩하지 않는다.

Always는 짧아야 한다. 프로젝트 전체의 헌법처럼 쓰되, 세부 구현법까지 넣지 않는다.

Auto Attached: 파일 패턴에 따라 자동 적용

Auto Attached 규칙은 특정 파일이나 폴더를 다룰 때 자동으로 붙는 규칙이다.

예를 들어 React 컴포넌트 파일에만 UI 규칙을 적용할 수 있다.

---
description: React 컴포넌트 작성 규칙
globs:
  - "src/**/*.tsx"
alwaysApply: false
---

## 원칙
- 기존 디자인 토큰을 우선 사용한다.
- 임의의 hex 색상을 추가하지 않는다.
- 버튼은 `src/components/ui/Button.tsx`를 재사용한다.
- loading, error, empty 상태를 함께 고려한다.

테스트 파일에는 테스트 규칙만 붙인다.

---
description: 테스트 작성 규칙
globs:
  - "src/**/*.test.ts"
  - "src/**/*.test.tsx"
alwaysApply: false
---

## 테스트 기준
- 외부 API는 실제 호출하지 않고 mock을 사용한다.
- 사용자 행동은 가능한 한 Testing Library의 userEvent로 표현한다.
- 구현 세부사항보다 화면에 보이는 결과를 검증한다.

이렇게 하면 Agent가 UI 작업을 할 때 테스트 규칙까지 읽느라 집중력을 잃지 않는다.

Agent Requested: 의도에 따라 불러오는 규칙

어떤 규칙은 파일 패턴만으로 판단하기 어렵다. 예를 들어 "결제 정책", "온보딩 플로우", "분석 이벤트 네이밍"은 여러 파일에 걸쳐 나타난다. 이럴 때는 description을 명확히 써서 Agent가 필요할 때 요청해 읽게 만든다.

---
description: 결제, 구독, 플랜 제한, 환불 관련 작업을 할 때 참고한다.
alwaysApply: false
---

## 결제 도메인 규칙
- 플랜 제한은 `src/billing/limits.ts`의 값을 기준으로 한다.
- 서버에서 권한을 다시 검증한다.
- 클라이언트 UI에서만 유료 기능 접근을 막으면 안 된다.
- 결제 실패 메시지는 사용자에게 원인을 단정하지 않는다.

description은 Agent에게 "언제 이 규칙을 읽어야 하는지" 알려 주는 표지판이다. 파일 이름보다 description이 더 중요할 때가 많다.

Manual: 드물지만 긴 절차

Manual 규칙은 사용자가 직접 붙일 때만 필요한 긴 절차에 적합하다. 예를 들어 마이그레이션 릴리스 절차, 장애 대응 절차, 대규모 리팩터링 체크리스트가 여기에 속한다.

항상 적용하기에는 길고, 자동으로 붙이기에는 상황이 복잡한 문서다. 이런 내용은 규칙보다 Skill로 빼는 편이 더 나을 수도 있다. 기준은 간단하다. 짧은 판단 기준이면 Rules, 긴 작업 절차면 Skills에 둔다.

좋은 .mdc 파일의 구조

좋은 규칙 파일은 문학적인 설명이 아니라 작업 가능한 지침이다. Agent가 빠르게 훑고 행동으로 옮길 수 있어야 한다.

기본 구조는 다음과 같다.

---
description: 이 규칙이 적용될 상황을 한 문장으로 설명한다.
globs:
  - "src/**/*.ts"
alwaysApply: false
---

## 목적
이 규칙이 왜 존재하는지 짧게 설명한다.

## 반드시 지킬 것
- 규칙 1
- 규칙 2
- 규칙 3

## 대표 파일
- `src/lib/api/client.ts`: API 호출 기본 클라이언트
- `src/features/auth/hooks/useSession.ts`: 세션 확인 패턴

## 금지 사항
- `fetch`를 컴포넌트에서 직접 호출하지 않는다.
- 토큰을 `localStorage`에 저장하지 않는다.

## 검증
- `pnpm lint`
- `pnpm test -- auth`

중요한 것은 네 가지다.

첫째, 상단에 목적과 적용 범위를 짧게 쓴다. 이 규칙이 언제 필요한지 분명해야 한다.

둘째, 반드시 따라야 할 규칙을 불릿으로 적는다. 긴 문단보다 짧은 명령형 문장이 낫다.

셋째, 대표 파일을 적는다. Agent는 추상적인 설명보다 실제 패턴이 있는 파일을 보고 더 안정적으로 따라 한다.

넷째, 검증 명령어를 적는다. "잘 구현해"보다 "변경 후 pnpm test -- auth를 실행하거나 실행하지 못한 이유를 보고해"가 낫다.

코드 스타일보다 먼저 적어야 할 것

규칙 파일을 만들 때 많은 사람이 들여쓰기, 네이밍, 세미콜론 같은 코드 스타일부터 적는다. 물론 스타일도 중요하다. 하지만 대부분의 프로젝트에서는 포매터와 린터가 이미 그 일을 한다.

Rules에 먼저 적어야 할 것은 Agent의 의사결정에 영향을 주는 정보다.

실행 환경과 명령어

Agent가 npm install을 실행했는데 프로젝트는 pnpm을 쓴다면 시작부터 꼬인다. 가장 먼저 패키지 매니저와 주요 명령어를 적는다.

## 명령어
- 패키지 매니저는 `pnpm`만 사용한다.
- 개발 서버: `pnpm dev`
- 타입체크: `pnpm typecheck`
- 린트: `pnpm lint`
- 단위 테스트: `pnpm test`
- E2E 테스트: `pnpm test:e2e`

폴더 구조와 책임

Agent는 파일을 만들 수 있다. 그래서 어디에 만들어야 하는지 알려 줘야 한다.

## 폴더 구조
- 기능 단위 코드는 `src/features/{featureName}` 아래에 둔다.
- 공용 UI는 `src/components/ui`에 둔다.
- 공용 유틸은 `src/shared`에 둔다.
- API 클라이언트는 `src/lib/api`의 기존 구조를 따른다.
- 새 top-level 폴더는 사용자 승인 없이 만들지 않는다.

API 호출과 에러 처리

API 호출 방식은 프로젝트의 안정성에 직접 영향을 준다.

## API 호출
- 컴포넌트에서 `fetch`를 직접 호출하지 않는다.
- 모든 API 호출은 `src/lib/api/client.ts`를 통한다.
- 401 응답은 세션 만료 처리 흐름을 따른다.
- 사용자에게 표시할 에러 메시지는 `getUserFacingErrorMessage`를 사용한다.

상태 관리

상태 관리 규칙이 없으면 Agent는 새 라이브러리를 추가하거나 기존 패턴과 다른 구조를 만들 수 있다.

## 상태 관리
- 서버 상태는 React Query를 사용한다.
- URL에 남아야 하는 필터 값은 search params로 관리한다.
- 모달 열림 여부 같은 UI 상태는 로컬 state로 둔다.
- 전역 store는 기존 store에 책임이 맞을 때만 확장한다.

보안상 금지할 구현

보안 규칙은 짧고 단호해야 한다.

## 보안 금지 사항
- 비밀 키를 클라이언트 번들에 포함하지 않는다.
- 결제 권한은 서버에서 다시 검증한다.
- 관리자 기능은 UI 숨김만으로 보호하지 않는다.
- production DB를 수정하는 스크립트는 사용자 승인 없이 작성하거나 실행하지 않는다.

이런 규칙은 코드 스타일보다 훨씬 중요하다. Agent가 잘못된 아키텍처 결정을 내리는 것을 막기 때문이다.

규칙은 처음부터 완벽할 필요가 없다

.cursor/rules/를 처음 만드는 날 모든 규칙을 다 쓰려고 하면 실패한다. 프로젝트의 모든 관례를 한 번에 문서화하려고 하면 파일만 길어지고 실제로 쓰이지 않는다.

작게 시작한다.

.cursor/rules/
  00-core.mdc
  01-commands.mdc
  02-testing.mdc
  03-security.mdc

처음에는 네 파일이면 충분하다.

• 00-core.mdc: 항상 지킬 최소 원칙

• 01-commands.mdc: 패키지 매니저와 실행 명령어

• 02-testing.mdc: 테스트 작성과 실행 기준

• 03-security.mdc: 절대 하면 안 되는 보안 실수

그다음부터는 실제 사건을 기준으로 갱신한다.

Agent가 API 클라이언트를 무시하고 fetch를 직접 썼다면 API 규칙을 추가한다.

PR 리뷰에서 "이 컴포넌트는 기존 Button을 써야 한다"는 지적이 반복되면 UI 규칙을 추가한다.

테스트 없이 리팩터링하는 일이 반복되면 testing 규칙을 강화한다.

반대로 오래된 규칙은 삭제해야 한다. 프로젝트가 React Query에서 다른 도구로 옮겼는데 rules에는 React Query를 쓰라고 남아 있으면 Agent는 틀린 지시를 따른다. 낡은 규칙은 없는 것보다 나쁘다.

월 1회 정도는 .cursor/rules/를 열어 다음을 확인한다.

• 실제 코드와 맞지 않는 규칙이 있는가?

• 같은 내용이 여러 파일에 중복되어 있는가?

• 너무 긴 Always 규칙이 있는가?

• 더 이상 쓰지 않는 명령어가 남아 있는가?

• 최근 Agent 실수 중 규칙으로 막을 수 있는 것이 있는가?

Rules는 문서가 아니라 운영 장치다. 살아 있어야 한다.

규칙을 테스트하는 방법

규칙을 만들었다고 바로 믿으면 안 된다. 간단한 프롬프트로 확인한다.

예를 들어 API 규칙을 만들었다면 새 대화에서 이렇게 요청해 본다.

사용자 목록을 불러오는 간단한 훅을 만들어 줘.

Agent가 기존 API 클라이언트를 찾는지, 컴포넌트에서 직접 fetch를 쓰지 않는지, 에러 처리 패턴을 따르는지 확인한다.

보안 규칙을 만들었다면 일부러 위험한 요청도 해 본다.

관리자 여부를 localStorage 값으로 판단해서 버튼을 숨겨 줘.

좋은 규칙이라면 Agent는 이 요청을 그대로 구현하지 않고, 서버 권한 검증이 필요하다고 말해야 한다.

규칙 테스트는 거창할 필요가 없다. Agent가 이전에 자주 하던 실수를 다시 시켜 보고, 같은 실수를 하지 않는지 확인하면 된다.

Rules는 Agent에게 주는 프로젝트 온보딩 문서다

새로운 개발자가 프로젝트에 들어오면 README, 폴더 구조, 테스트 명령어, 금지 패턴을 알려 준다. Cursor Agent도 다르지 않다. 다만 Agent는 매번 새로 들어오는 사람처럼 행동할 수 있다. 그래서 온보딩 문서를 매번 말로 설명하는 대신 .cursor/rules/에 저장해야 한다.

좋은 Rules는 Agent를 더 똑똑하게 만드는 것이 아니라, 덜 흔들리게 만든다. 매번 다른 스타일의 코드를 만들지 않게 하고, 프로젝트가 이미 선택한 방식을 따르게 한다.

솔로 메이커에게 이것은 특히 중요하다. 혼자 일하면 리뷰어도, 시니어 개발자도, QA도 따로 없다. 그래서 규칙이 두 번째 동료가 된다. Agent가 작업하고, Rules가 기준을 제공하고, 당신이 최종 판단한다.

반복되는 지시는 규칙으로 옮겨라. 반복되는 실수는 규칙으로 막아라. 오래된 규칙은 삭제하라. 그렇게 관리되는 .cursor/rules/는 단순한 설정 폴더가 아니라, 제품을 오래 유지하기 위한 살아 있는 프로젝트 매뉴얼이 된다.

참고

¹How to write great Cursor Rules