당신은 .cursor/rules 파일을 작성했습니다. 규칙도 훌륭합니다. 하지만 에이전트는 계속해서 이를 무시합니다.

열에 아홉은 모델이 멍청해서 발생하는 문제가 아닙니다. 애초에 규칙이 컨텍스트(context)에 **연결(attached)**되지 않았기 때문입니다. Cursor에는 규칙이 채팅에 진입하는 네 가지 방법이 있으며, 각 방법은 서로 다른 프론트매터(frontmatter) 필드에 의해 제어됩니다. 프론트매터를 잘못 작성하면 규칙은 디스크에 저장된 채 아무런 역할도 하지 못하고 머물러 있게 됩니다.

전체 모델과, 규칙을 조용히 비활성화시키는 세 가지 실수에 대해 알아보겠습니다.

네 가지 규칙 유형

.cursor/rules/*.mdc에 있는 규칙은 프론트매터에 따라 네 가지 유형 중 하나가 됩니다:

마지막 행을 다시 읽어보세요: alwaysApply, globs, 그리고 description이 없는 규칙은 Manual(수동)입니다. 이는 스스로 절대 실행되지 않습니다. 규칙이 "아무것도 하지 않는" 가장 큰 이유는 바로 이것입니다. 조용히 수동 모드로 기본 설정되었고, 당신이 이를 @-mention(언급)하지 않았기 때문입니다.

실수 1: globs를 YAML 배열로 작성하는 것

이것이 가장 흔한 실수입니다. globs는 **따옴표가 없는, 쉼표로 구분된 단순 문자열(bare, comma-separated string)**이어야 합니다. YAML 리스트 형태나 따옴표로 감싸진 형태가 아닙니다:

---
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
...

대신 사람들이 흔히 작성하며, 이로 인해 조용히 연결에 실패하는 방식은 다음과 같습니다:

---
globs:
  - "src/**/*.ts"        # 배열 형태 — 일치하지 않음
...

---
globs: "src/**/*.ts"     # 따옴표 사용 — 일치하지 않음
---

글로브(glob) 구문 자체는 표준을 따릅니다: *는 하나의 경로 세그먼트와 일치하며, **는 임의의 수의 디렉토리와 일치합니다. src/**/*.tsx, **/*.ts, 그리고 tailwind.config.*는 모두 유효합니다. 여러 패턴은 쉼표로 구분하여 한 줄에 작성합니다: docs/**/*.md, docs/**/*.mdx.

실수 2: .mdc 대신 .md 사용

규칙은 반드시 .mdc 확장자를 사용해야 합니다. .cursor/rules/ 폴더에 일반 .md 파일을 넣으면 무시됩니다. 에러나 경고도 발생하지 않으며, 단순히 규칙으로 인식되지 않을 뿐입니다. 만약 README나 gist에서 규칙을 복사해 붙여넣었다면, 다른 무엇보다 확장자를 먼저 확인하십시오.

실수 3: 설명(description)이 없는 Agent-Requested 규칙

"Apply Intelligently" 규칙은 가장 유용한 유형입니다. 에이전트가 엄격한 glob 패턴 대신 관련성이 있을 때 규칙을 가져오기 때문입니다. 하지만 이 결정은 전적으로 description 필드에 의해 이루어집니다. 설명이 없으면 에이전트가 매칭할 대상이 없으므로, Agent-Requested 규칙은 결국 Manual 규칙으로 전락하여 결코 나타나지 않게 됩니다.

설명을 제목이 아닌 트리거(trigger)로 작성하십시오:

---
description: Vitest 단위 테스트 작성 및 명명 규칙
alwaysApply: false
...

"Testing rules"는 제목입니다. "Vitest 단위 테스트 작성 및 명명 규칙"은 에이전트가 들어오는 요청과 실제로 매칭할 수 있는 내용입니다.

규칙이 실제로 적용되었는지 확인하는 방법

추측하지 말고 직접 확인하십시오. 메시지를 보낼 때, Cursor는 채팅 컨텍스트의 일부로 해당 턴에 가져온 규칙들을 화면에 표시합니다. 만약 규칙이 해당 목록에 없다면 작동하지 않은 것이며, 이제 세 가지 실수 중 무엇을 확인해야 할지 알게 된 것입니다. 이 "적용되었는가?"를 확인하는 루프는 규칙을 디버깅하는 가장 빠른 방법이며, 대부분의 사람들이 모델을 탓하며 건너뛰는 바로 그 단계입니다.

규칙은 어떤 유형이어야 하는가?

• 프로젝트 전반에 걸쳐 있으며 타협 불가능한 경우 (예: any 사용 금지, 항상 키워드 인자 사용): Always.
• 스택 또는 폴더 특정적인 경우 (예: React 컴포넌트 컨벤션, 마이그레이션 파일 형식): glob을 사용한 Auto Attached.
• 상황에 따라 다르며 판단이 중요한 경우 (예: 테스트 작성 방법, ADR 구조화 방법): 명확한 설명을 포함한 Agent Requested.
• 드물게 필요할 때만 사용하는 스캐폴딩(scaffolding): Manual, 그리고 필요할 때 @-mention으로 호출.

건강한 규칙 디렉토리는 대부분 Auto Attached와 Agent Requested로 구성되며, 소수의 Always 규칙이 상위에 위치합니다. 모든 것이 Always라면 모든 프롬프트가 비대해질 뿐이며, 모든 것이 Manual이라면 아무것도 작동하지 않습니다.

한 줄 요약

“작동하지 않는” Cursor 규칙은 거의 항상 규칙이 한 번도 연결(attached)되지 않은 경우입니다. 확장자(.mdc)를 확인하고, globs가 쉼표로 구분된 순수 문자열(bare comma-separated string)인지 확인하며, Agent-Requested 규칙에 실제 설명(description)을 부여하세요. 그런 다음 규칙의 실제 내용을 수정하기 전에 컨텍스트 리스트(context list)를 확인하여 규칙이 실행(fired)되었는지 확인하십시오.

전체 .cursor/rules 세트와 Claude Code 및 Codex 대응물을 수동으로 유지 관리하는 것은 매우 힘든 일입니다. 이것이 제가 Rulestack에서 만들고 있는 것입니다. Cursor, Claude Code, Codex를 위한 프로덕션 준비 완료된(production-ready) 규칙 팩을 제공합니다.

또한 Bluesky에서 짧은 AI 코딩 에이전트 팁을 게시하고 있습니다 — @ai-shop.bsky.social에서 팔로우하세요.