Cursor Agent Mode에서 .cursorrules 파일이 작동하지 않는 이유: 마이그레이션 가이드

만약 .cursorrules를 작성하는 데 시간을 보냈음에도 Cursor의 에이전트 모드(agent mode)가 계속해서 당신의 컨벤션(conventions)을 무시한다면 — 이는 당신의 규칙에 버그가 있는 것이 아닙니다. 이는 당신이 전혀 경고받지 못한 형식 불일치(format mismatch) 문제입니다.

Cursor에는 두 개의 별도 규칙 로딩 시스템이 있습니다. 에이전트 모드(agent mode)는 그중 하나만 읽습니다. .cursorrules는 다른 하나에 공급됩니다.

이 가이드는 정확한 마이그레이션(migration) 과정을 다룹니다: 무엇을 변경해야 하는지, 파일이 어디로 가야 하는지, 그리고 오늘 바로 적용할 수 있는 네 가지 구체적인 .mdc 예시를 제공합니다.

형식의 분리: 무엇이 무엇을 읽는가

속성	.cursorrules	.mdc (Project Rules)
위치	프로젝트 루트 (Project root)	.cursor/rules/*.mdc
...

이러한 아키텍처(architectural) 분리가 존재하는 이유는 .cursorrules가 Cursor의 에이전트 모드 컨텍스트 파이프라인(agent-mode context pipeline)보다 먼저 만들어졌기 때문입니다. 이것은 폐기(deprecated)된 것이 아닙니다 — Ask/Edit 모드에서는 여전히 작동합니다. 하지만 에이전트 모드(agent mode)는 .cursor/rules/에서 .mdc 파일만 읽는 다른 컨텍스트 로더(context loader)에서 실행됩니다.

새로운 에이전트 세션을 열고 활성화된 프로젝트 규칙(project rules)의 이름을 말해달라고 요청함으로써 이를 확인할 수 있습니다. 만약 .cursorrules만 가지고 있다면, 에이전트는 규칙이 없다고 답할 것입니다.

.mdc 프론트매터(frontmatter) 형식

모든 .mdc 파일에는 YAML 프론트매터(frontmatter) 블록이 필요합니다. 중요한 세 가지 필드는 다음과 같습니다:

---
description: "이 규칙 파일이 다루는 내용"
alwaysApply: true
...

• description — Cursor의 규칙 패널(rules panel)에 표시되며, 컨텍스트 관련성 점수(context relevance scoring)를 매기는 데 사용됩니다.
• alwaysApply — true는 모든 에이전트 실행 시 로드됨을 의미하며, false는 glob 패턴이 활성 파일과 일치할 때만 로드됨을 의미합니다.
• globs — 규칙을 특정 파일 유형으로 제한하는 glob 패턴 배열입니다. 전역 규칙(global rules)의 경우 생략합니다.

alwaysApply: true와 특정 glob의 조합이 가장 신뢰할 수 있는 설정입니다: 규칙은 항상 로드되지만, 일치하는 파일이 컨텍스트에 있을 때 높은 관련성(high-relevance)을 가진 것으로 처리됩니다.

Gist에서 가져온 네 가지 마이그레이션 예시

마이그레이션 Gist에는 바로 사용할 수 있는 네 개의 .mdc 파일이 있습니다. 각 파일이 무엇을 하는지, 그리고 왜 그런 구조로 되어 있는지 설명합니다.

1. typescript.mdc — 엄격 모드(strict-mode) 강제

---
description: TypeScript strict-mode enforcement
globs: ["**/*.ts", "**/*.tsx", "!**/*.test.ts", "!**/*.spec.ts"]
...

테스트 파일에 대한 glob 제외 설정(!**/*.test.ts)에 주목하세요. 테스트 파일은 (mock, stub 등을 위해) 정당하게 더 느슨한 타이핑 (typing)이 필요합니다. 이를 제외함으로써 잘못된 준수 실패 (false compliance failures)를 방지할 수 있습니다.

2. no-any.mdc — 단일 관심사 규칙 파일 (single-concern rule file)

---
description: Enforce no-any TypeScript rule
globs: ["**/*.ts", "**/*.tsx"]
...

이 파일은 의도적으로 typescript.mdc와 별개의 파일로 존재합니다. 짧고 단일 관심사(single-concern)를 가진 파일은 길고 여러 규칙이 섞인 파일보다 채택률 (pickup rates)이 더 높습니다. 에이전트 모드 (agent mode)가 컨텍스트 (context)를 압축할 때, 파일당 관련성을 평가합니다. 즉, 하나의 주제를 다루는 짧은 파일이 여러 주제를 다루는 긴 파일보다 더 높은 점수를 받습니다.

3. react.mdc — 프레임워크 특정 규칙 (framework-specific rules)

---
description: React + Next.js App Router production rules
globs: ["**/*.tsx", "**/*.jsx", "src/**/*.ts"]
...

src/**/*.ts glob은 서버 액션 (server action) 파일을 포착하기 위해 존재합니다. 이 파일들은 .ts 확장자를 가지지만 React 컴포넌트와 함께 src 트리 내에 위치합니다. 이 설정이 없다면, 서버 액션 파일은 App Router 컨벤션 (conventions)이 아닌 TypeScript 규칙만 트리거하게 됩니다.

4. api-errors.mdc — API 레이어에 범위 제한 (scoped to API layer)

---
description: API error handling patterns
globs: ["**/api/**/*.ts", "**/routes/**/*.ts", "**/handlers/**/*.ts", "**/*.controller.ts"]
...

이 파일은 alwaysApply: false를 사용합니다. API 라우트 (route) 파일을 편집할 때만 관련이 있으므로, 모든 에이전트 실행 시마다 로드할 이유가 없습니다. glob 설정이 충분히 구체적이어서 Cursor는 정확히 필요할 때만 이 파일을 로드할 것입니다.

마이그레이션 절차

1단계 — 규칙 디렉토리 생성:

mkdir -p .cursor/rules

2단계 — 복사하지 말고 분할하세요. 만약 기존의 .cursorrules가 TypeScript, React, API 컨벤션을 포함하여 80줄에 달한다면, 이를 하나의 .mdc 파일로 붙여넣지 마세요. typescript.mdc, react.mdc, api.mdc로 분할하세요. 파일당 하나의 도메인(domain)을 할당해야 합니다.

3단계 — 각 파일에 프론트매터 (frontmatter) 추가:

---

description: "<이 파일이 관리하는 내용>"
alwaysApply: true
...

4단계 — 부정적인 규칙을 긍정적인 규칙으로 다시 작성하세요. "var를 절대 사용하지 마세요" → "const 또는 let만 사용하세요." "any를 사용하지 마세요" → "모든 타입은 명시적이어야 합니다." 긍정적인 명령문(Positive imperatives)이 에이전트 모드(agent mode)에서 준수율이 더 높습니다.

5단계 — 각 파일을 50행 미만으로 유지하세요. 파일이 길어지면 컨텍스트 압축(context compaction) 과정에서 조용히 우선순위가 밀리게 됩니다. 특정 도메인에 50행 이상의 규칙이 필요하다면, 두 개의 파일로 분할하세요.

6단계 — 마이그레이션 검증:

for f in .cursor/rules/*.mdc; do
  echo "=== $f ==="
  head -6 "$f"
...

모든 파일의 처음 6행 이내에 description:과 alwaysApply:가 표시되어야 합니다. 만약 파일이 --- 구분자 없이 규칙 텍스트로 시작한다면, 로드되지 않을 것입니다.

7단계 — .cursorrules 이름 변경: 아직 삭제하지 마세요. .cursorrules.bak로 이름을 변경하세요. 만약 Ask/Edit 모드의 동작이 변한다면 그 이유를 알 수 있으며 원본을 참조할 수 있습니다. 에이전트 모드가 정상 작동하는 것을 일주일 동안 확인한 후에 삭제하세요.

마이그레이션이 해결하는 문제

이전에는 에이전트 모드에서 전혀 효과가 없던 규칙들이, 다음의 형식 요구 사항을 충족한다는 가정하에 마이그레이션 직후 즉시 작동하기 시작합니다:

• .cursor/rules/ 디렉토리에 .mdc 확장자로 존재함
• 프론트매터 (frontmatter)에 alwaysApply: true가 포함됨
• description: 필드가 있음
• 대상 파일 유형과 일치하는 범위 지정된 globs:가 있음
• 50행 미만임
• 각 규칙이 하나의 명령문(imperative sentence)으로 구성됨

대부분의 .cursorrules 파일은 정의상 처음 세 가지 조건을 충족하지 못합니다. 그것이 바로 문제의 핵심입니다.

무료: 4개의 .mdc 파일 받기

위의 네 가지 파일은 Cursor rules migration Gist에 있습니다. 파일을 다운로드하여 .cursor/rules/에 넣으면, 여러분의 TypeScript/React/API 컨벤션(conventions)이 에이전트 모드에서 즉시 활성화됩니다.

만약 다른 스택(Go, Python, Rust, Node, Next.js, Svelte 등)을 위한 규칙이 필요하다면 — Cursor Rules Pack이 14개 스택에 걸쳐 프로덕션 환경에서 검증된 50개의 규칙을 제공합니다. 이 규칙들은 올바른 프론트매터 (frontmatter), 글로브 스코핑 (glob scoping), 그리고 에이전트 모드 준수 (agent-mode compliance) 사항이 내장된 .mdc 형식으로 사전 구조화되어 있습니다. 단 한 번의 $27 결제로 즉시 다운로드할 수 있습니다.