AI 출력을 실제로 개선하는 Cursor 규칙 (.mdc 프로젝트 규칙)

온라인에서 보는 대부분의 Cursor 규칙들은 희망 사항 목록에 불과합니다. "클린 코드를 작성하라(Write clean code)." "베스트 프랙티스(best practices)를 따르라." "간결하게 작성하라." Cursor는 이를 읽고 정중하게 고개를 끄덕이지만, 규칙이 없을 때와 정확히 똑같은 코드를 내놓습니다.

이유는 간단합니다. 모호한 규칙은 모델이 실행할 수 있는 근거를 제공하지 않기 때문입니다. 규칙은 오직 구체적(specific)이고, 강제 가능하며(enforceable), 중요한 시점에 범위가 지정(scoped)될 때만 출력을 변화시킵니다. 이 세 가지 속성을 중심으로 규칙을 다시 작성한 후, Cursor는 대부분의 요청에서 "작동은 하지만 코드 리뷰에서 거절할 만한 코드"에서 "한 번에 리뷰를 통과하는 코드"로 진화했습니다.

바로 복사해서 붙여넣을 수 있는 실제 .mdc 규칙들과 함께, 실제로 효과를 본 방법들을 소개합니다.

형식: .cursorrules가 아닌 .cursor/rules/*.mdc

Cursor는 .cursor/rules/ 폴더에 .mdc 파일로 저장되는 프로젝트 규칙 (Project Rules) 방식으로 전환되었습니다. 기존의 단일 .cursorrules 파일과 비교했을 때 가장 큰 장점은 **범위 지정 (scoping)**입니다. 각 규칙에는 언제 로드될지를 제어하는 프론트매터 (frontmatter)가 포함되어 있습니다.

---
description: "모든 코드를 위한 보안 규칙"
globs:
...

세 가지 프론트매터 필드가 모든 것을 결정합니다:

• alwaysApply: true — 모든 요청 시 규칙이 컨텍스트 (context)에 포함됩니다. 짧고 보편적인 규칙(보안, 에러 핸들링)에 사용하세요.
• globs: "**/*.tsx" — 일치하는 파일이 작업 중일 때만 규칙이 자동으로 부착됩니다. React 규칙이 Python 컨텍스트를 오염시키지 않도록 스택 특정적 (stack-specific) 규칙에 사용하세요.
• 둘 다 설정하지 않음 — 에이전트(agent)가 description을 바탕으로 관련이 있다고 판단할 때 규칙을 가져옵니다. 상황별 베스트 프랙티스 규칙에 사용하세요.

이 범위 지정 (scoping)이 핵심입니다. 모든 요청마다 모든 규칙을 로드하면 컨텍스트가 희석되어 모델이 모든 규칙을 무시하기 시작합니다. 범위가 지정된 규칙은 관련 있는 규칙만 존재하기 때문에 날카로움을 유지할 수 있습니다.

규칙 1: 모델이 실제로 강제할 수 있는 글로벌 규칙

항상 적용되는 규칙은 열망이 아닌 구체적인 체크리스트 형태로 짧게 작성하세요:

---
description: 글로벌 엔지니어링 규칙 — 항상 적용
globs:
...

"clean code를 작성하라"와 같은 문구는 없습니다. 모든 문장은 모델이 특정 diff (차이점)에 적용할 수 있는 체크리스트입니다. "경계에서 입력을 검증하라"는 zod 스키마를 생성하지만, "clean code를 작성하라"는 아무것도 생성하지 못합니다.

규칙 2: glob으로 범위를 지정한 스택 규칙 (stack rule)

이 규칙은 TypeScript/React 파일이 포함된 경우에만 로드되므로, 백엔드나 스크립트 작업에는 전혀 간섭하지 않습니다:

---
description: React + TypeScript 컨벤션 (conventions)
globs: "**/*.tsx, **/*.ts"
...

no any 규칙은 사람들이 과소평가하는 규칙입니다. 그대로 두면 Cursor는 저항이 가장 적은 경로인 any를 끊임없이 사용합니다. 범위를 지정한 한 줄의 규칙이 any 사용의 대부분을 제거하고, 모델이 실제 타입 (type)에 대해 생각하도록 강제합니다.

규칙 3: 에이전트가 필요할 때 로드하는 베스트 프랙티스 (best-practice) 규칙

데이터베이스 액세스와 같이 어떤 규칙들은 특정 상황에서만 중요합니다. alwaysApply를 꺼두고 명확한 description (설명)을 작성하면, 에이전트가 SQL을 다룰 때 해당 규칙을 가져옵니다:

---
description: 데이터베이스 및 SQL 안전성 — 쿼리 또는 마이그레이션 작성 시 적용
globs:
...

이 규칙은 항상 로드되는 것이 아니기 때문에, CSS 작업 시 컨텍스트 (context)를 잡아먹지 않습니다. 하지만 Cursor에게 쿼리 작성을 요청하는 순간, 설명(description) 덕분에 관련성이 확보되어 규칙이 로드됩니다.

나를 설득시킨 Before/After

동일한 요청 — "사용자의 주문을 가져오는 엔드포인트(endpoint)를 추가해줘" — 에 대해 위 규칙들이 있을 때와 없을 때의 차이입니다.

규칙이 없을 때:

app.get("/orders", async (req, res) => {
  const userId = req.query.userId;
  const orders = await db.query(`SELECT * FROM orders WHERE user_id = ${userId}`);
...

SQL 인젝션 (SQL injection), 입력 검증 (input validation) 부재, 페이지네이션 (pagination) 부재, SELECT * 사용.

규칙이 있을 때:

const Query = z.object({ userId: z.string().uuid(), page: z.coerce.number().min(1).default(1) });

app.get("/orders", async (req, res) => {
...

매개변수화 (parameterized), 검증됨 (validated), 페이지네이션 적용, 명시적 컬럼 (explicit columns) 사용. 동일한 모델, 동일한 프롬프트 (prompt)였지만, 규칙이 이 결과를 만들어냈습니다.

과하지 않게 시작하는 방법

첫날부터 20개의 규칙을 작성하지 마세요. 컨텍스트 (context)가 희석되고 규칙을 유지 관리하다가 지쳐버릴 것입니다. 정확히 세 가지만으로 시작하세요:

1. 하나의 짧은 alwaysApply 전역 규칙 (보안 + 에러 핸들링 (error handling)).
2. 주요 스택을 위한 하나의 glob-scoped 규칙.
3. 가장 골치 아픈 문제를 해결하기 위한 하나의 온디맨드 (on-demand) 규칙 (SQL, 접근성 (accessibility), 테스트 (tests) 등).

일주일 동안 이 규칙들과 함께 지내보세요. 그러다 Cursor가 동일한 실수를 두 번 반복하는 것을 발견했을 때만 규칙을 추가하세요. 규칙은 실제적이고 반복되는 오류를 방지함으로써 그 자리를 얻게 됩니다.

완벽하게 튜닝된 AI 코딩 설정을 원한다면

규칙은 그림의 절반일 뿐입니다. 나머지 절반은 AI 어시스턴트에게 실제 워크플로우 (workflow)를 제공하는 것입니다. 즉, 모든 것을 수행하는 하나의 제너럴리스트 (generalist) 대신, 집중된 리뷰/테스트/리팩터링 (review/test/refactor) 단계를 제공하는 것입니다. 저는 저의 전체 설정을 **Claude Code Agent OS**로 패키징했습니다. 여기에는 26개의 특화된 서브에이전트 (subagents), 12개의 슬래시 커맨드 (slash commands), 즉시 편집 가능한 CLAUDE.md 템플릿, MCP 설정, 그리고 안전 장치 (safety hooks)가 포함되어 있습니다. 이는 위에서 언급한 규칙들과 동일한 '범위 지정 및 불필요한 요소 제거 (scoped, anti-fluff)' 철학을 전체 코딩 루프 (coding loop)에 적용한 것입니다. 이는 Cursor 및 모든 에디터와 함께 작동합니다.

그럼에도 불구하고, 이 포스트에서 소개한 세 가지 규칙 스타터는 비용이 전혀 들지 않으며 여러분의 바로 다음 Cursor 세션을 개선해 줄 것입니다. 이것들을 먼저 구축한 다음, 전체 설정을 원하는지 결정하세요.

여러분의 코드베이스에서 Cursor가 계속 반복하는 한 가지 실수는 무엇인가요? 댓글로 알려주시면 그에 맞는 규칙을 제안해 드리겠습니다.