AI 생산성을 저해하는 5가지 .cursorrules 안티패턴 (Antipatterns)

여러분의 .cursorrules 파일은 아마 여러분이 생각하는 대로 작동하지 않고 있을 것입니다.

Cursor가 고장 났기 때문이 아닙니다. 대부분의 .cursorrules 설정이 동일한 다섯 가지 실수를 범하고 있기 때문입니다. 그 실수가 무엇인지, 그리고 어떻게 해결해야 하는지 알려드리겠습니다.

실수 1: 하나의 파일에 모든 것을 담는 것

가장 흔한 .cursorrules 안티패턴 (Antipattern)은 모놀리스 (Monolith) 구조입니다. 프로젝트 루트에 위치한 300줄짜리 파일 하나가 TypeScript 컨벤션 (Conventions), API 인증 패턴 (Auth patterns), 배포 노트 (Deployment notes), 그리고 "항상 깨끗한 코드를 작성할 것"이라는 내용까지 모두 다루는 방식입니다.

문제점: Cursor는 여러분이 무엇을 편집하고 있든 관계없이 이 파일을 모든 컨텍스트 (Context)에 로드합니다. CSS 버그를 수정하고 있을 때, SQL 쿼리 규칙이 아무런 쓸모없이 토큰 예산 (Token budget)을 낭비하게 됩니다. 컨텍스트가 길어지면 오래된 규칙들은 압축되어 사라지는데, 이는 가장 중요한 제약 조건들이 사라질 가능성이 가장 높다는 것을 의미합니다.

해결책: 범위가 지정된 규칙 파일들로 분리하세요.

.cursorrules                  # 50줄: 프로젝트 개요, 스택, 타협 불가능한 원칙
src/api/.cursorrules          # 인증 패턴, 에러 형식, 속도 제한 (Rate limiting)
src/components/.cursorrules   # 컴포넌트 컨벤션, 상태 패턴 (State patterns)
...

각 파일은 해당 디렉토리의 파일이 열려 있을 때만 로드됩니다. 여러분의 전체 인-컨텍스트 (In-context) 규칙 예산은 타이트하게 유지됩니다.

실수 2: 모호한 제약 조건

"깨끗하고 읽기 쉬운 코드를 작성하세요."
"함수를 작게 유지하세요."
"베스트 프랙티스 (Best practices)를 따르세요."

이것들은 규칙이 아닙니다. 열망일 뿐입니다. AI는 이미 "베스트 프랙티스"가 무엇을 의미하는지 알고 있으며, 여러분의 해석이 아닌 AI 자신의 해석을 적용할 것입니다.

규칙은 실패할 수 있을 정도로 충분히 구체적이어야 합니다. 만약 해당 규칙을 위반하는 구체적인 코드 샘플을 상상할 수 없다면, 그 규칙은 강제하기에 너무 모호한 것입니다.

모호함: "에러를 적절히 처리하세요."
구체적: "모든 비동기 (Async) 함수는 반드시 try/catch를 포함해야 합니다. 에러는 다시 던지기(Rethrowing) 전에 반드시 logger.error()를 통해 로그를 남겨야 합니다. 에러를 조용히 삼키지 마세요."

모호함: "서술적인 변수 이름을 사용하세요."
구체적: "불리언 (Boolean) 변수는 반드시 is, has, should, 또는 can으로 시작해야 합니다. 루프 인덱스를 제외하고는 한 글자 이름을 사용하지 마세요."

두 번째 버전은 자동화가 가능합니다. 첫 번째 버전은 단순한 느낌(vibes)일 뿐입니다.

실수 3: 프로젝트 구조 컨텍스트(Project structure context) 부재

AI는 당신이 알려주지 않으면 프로젝트 레이아웃을 알지 못합니다. 이는 잘못된 경로에서의 임포트(import), 잘못된 디렉토리에 생성되는 새 파일, 그리고 이미 존재하는 헬퍼 함수(helper function)를 AI가 인지하지 못해 중복 생성하는 문제로 이어집니다.

.cursorrules 파일 초반에 간결한 디렉토리 맵을 추가하세요:

Project structure:
src/
  api/          # Express routes + middleware
...

단 여덟 줄입니다. services/ 디렉토리가 존재한다는 것을 몰라서 AI가 라우트 핸들러(route handler) 안에 데이터베이스 호출 코드를 집어넣는 상황을 방지하기에 충분한 양입니다.

실수 4: 코드베이스와 모순되는 규칙

만약 .cursorrules에는 "any 타입을 절대 사용하지 마세요"라고 적혀 있는데, 실제 코드베이스에 200개의 any 타입 사용 사례가 있다면, 그 규칙은 기존 코드와 싸우게 됩니다. AI는 상충하는 신호를 받게 됩니다. 규칙은 한 가지를 말하고, 코드베이스의 예시는 다른 것을 말하기 때문입니다. 대개 예시가 승리합니다.

당신의 규칙은 코드가 '바뀌었으면 하는 모습'이 아니라, 코드가 '이미 수행하고 있는 방식'을 설명해야 합니다.

만약 격차가 존재한다면 — 즉, 새로운 패턴을 도입하고 싶지만 코드베이스가 아직 그 수준에 도달하지 못했다면 — 이를 명시적으로 언급하세요:

# 마이그레이션 진행 중: `any` 타입을 제거하고 있습니다.
# 새로운 코드에는 `any`를 사용해서는 안 됩니다. 기존의 `any` 사용 사례는 점진적으로 수정될 예정입니다.
# 오래된 코드를 리팩터링(refactoring)할 때도 새로운 `any`를 추가하지 마세요.

이렇게 하면 모순을 만들지 않으면서도 AI에게 명확한 권한을 부여할 수 있습니다.

실수 5: 단일 진실 공급원(Source of truth) 없이 도구 간에 규칙 중복

Cursor와 Claude Code를 함께 사용한다면, .cursorrules와 CLAUDE.md가 거의 동일한 내용을 약간씩 다른 방식으로 말하게 됩니다. 그러다 하나는 업데이트되고 다른 하나는 업데이트되지 않으면, 두 파일은 서로 모순되게 됩니다. 결국 어느 쪽도 신뢰할 수 없게 됩니다.

해결책은 도구별 맞춤 설정을 갖춘 단일 권위 있는 소스(single authoritative source)를 만드는 것입니다:

핵심 프로젝트 규칙은 CLAUDE.md에 유지하세요 (가장 구조화된 형식이며, Claude Code에 의해 시스템 프롬프트 접두사(system prompt prefix)로 로드됩니다).
.cursorrules가 동일한 핵심 규칙을 가져오거나 참조하도록 하여, Cursor 전용 포맷/동작만 추가하세요.
규칙을 업데이트할 때는 각 도구의 파일을 개별적으로 수정하지 말고, 소스(source)를 업데이트하세요.

신규 프로젝트(greenfield projects)의 경우, 두 파일이 이미 올바르게 연결된 프로덕션 구성 스타터(production-configured starter)로 시작하면 이러한 설정 비용을 완전히 절약할 수 있습니다. Vibe Coder Kit에는 .cursorrules와 CLAUDE.md가 이미 동기화되어 있고 실제 코드베이스 구조와 일치하는 12개의 스타터(Next.js SaaS, Express + JWT, FastAPI, Discord Bot 등)가 포함되어 있습니다.

좋은 규칙 파일의 테스트 방법

각 규칙을 읽고 다음과 같이 질문해 보세요: "개발자가 규칙을 진심으로 따르려고 노력하는 과정에서 이 규칙을 위반할 가능성이 있는가?" 만약 그렇다면, 그 규칙은 너무 모호한 것입니다. 위반 여부가 명확해질 정도로 충분히 구체적으로 만드세요.

그다음 줄 수를 세어보세요. 만약 .cursorrules가 100줄을 넘는다면 분할하세요. 만약 20줄 미만이라면, 아직 실제 컨벤션(conventions)을 제대로 포착하지 못한 것일 가능성이 높습니다.

짧게. 구체적으로. 범위를 제한하여. 코드베이스와 일관되게.

이 네 가지 제약 조건을 지키면, 여러분의 AI 코딩 설정이 데모에서 약속한 대로 작동할 것입니다.

BLN Craft는 AI 네이티브 워크플로(AI-native workflows)를 위한 개발자 도구를 만듭니다. blncraft.com에서 저희를 찾아보세요.