Cursor Rules 완전 가이드 — 일관된 AI 코딩의 비결

AI가 매번 다른 방식으로 코드를 짜는 문제

Cursor에서 AI에게 컴포넌트를 만들어달라고 하면, 어제는 TypeScript로, 오늘은 JavaScript로, 함수형으로 요청했더니 클래스형으로 돌아오는 상황이 반복된다. AI 코딩 도구를 처음 쓸 때 가장 먼저 부딪히는 문제가 바로 일관성 부재다.

Cursor는 대화 맥락이 끊기면 이전에 어떤 방식으로 코드를 작성했는지 기억하지 못한다. 새 채팅을 열 때마다 "우리 프로젝트는 TypeScript를 쓰고, 스타일링은 Tailwind를 쓰며, 컴포넌트는 함수형으로 작성합니다"를 반복해서 설명해야 한다면 AI 코딩의 효율이 절반 이하로 떨어진다. 결국 생성된 코드를 일일이 검토하며 수정하는 시간이 오히려 더 늘어나게 된다. Cursor Rules는 이 문제를 구조적으로 해결하기 위해 만들어진 기능이다.

이 문제는 단순히 AI의 능력 문제가 아니다. AI는 기본적으로 무상태(stateless)로 동작한다. 각 대화 세션이 독립적으로 시작되며, 이전 세션에서 무엇을 했는지 자동으로 기억하지 않는다. 따라서 일관성을 유지하려면 매번 컨텍스트를 명시적으로 제공하거나, 그 컨텍스트를 파일로 고정해야 한다.

Cursor Rules란 무엇인가

Cursor Rules(커서 룰스)는 Cursor IDE에 내장된 AI 지시 사전(instruction layer)이다. 프로젝트별 또는 전체 환경에 적용할 규칙을 텍스트 파일로 정의해두면, Cursor의 AI가 코드 생성·수정·설명 시 해당 규칙을 자동으로 참조한다.

쉽게 말하면 "팀 코딩 컨벤션 문서"를 AI가 항상 책상 위에 펼쳐두도록 만드는 장치다. 단, 단순한 비유에 그치지 않고 실제 동작 방식을 이해해야 올바르게 활용할 수 있다.

2026년 4월 기준, Cursor에서 Rules를 적용하는 방법은 두 가지다.

• User Rules (글로벌 규칙): Cursor 설정 화면에서 입력. 모든 프로젝트에 공통 적용.
• Project Rules (프로젝트 규칙): 프로젝트 루트의 .cursor/rules/ 디렉터리에 .mdc 파일로 작성. 프로젝트별로 독립 관리.

과거에는 프로젝트 루트에 .cursorrules 단일 파일로 관리하는 방식이 표준이었으나, 현재는 .cursor/rules/ 디렉터리 방식이 권장된다. 두 방식 모두 동작하지만, 이 글에서는 현재 권장 방식인 디렉터리 구조를 기준으로 설명한다.

User Rules와 Project Rules의 차이는 적용 범위(scope)다. User Rules는 Cursor가 설치된 환경에서 열리는 모든 프로젝트에 적용된다. "항상 한국어로 답변해라", "응답 길이를 간결하게 유지해라" 같은 개인 선호를 담기에 적합하다. 반면 Project Rules는 해당 프로젝트 디렉터리 안에서만 적용되며, 팀원이 같은 저장소를 클론하면 동일한 Rules를 공유할 수 있다는 장점이 있다.

Rules 파일의 구조와 네 가지 적용 방식

Project Rules의 각 파일은 .mdc(MDC, Markdown with Cursor metadata) 확장자를 사용한다. 파일 상단에 YAML frontmatter를 작성해 적용 방식을 제어한다.

frontmatter 핵심 필드

--- description: React 컴포넌트 작성 규칙 globs: ["src/components/**/*.tsx", "src/pages/**/*.tsx"] alwaysApply: fa

lse --- # React 컴포넌트 규칙 - 함수형 컴포넌트만 사용한다 - Props는 반드시 TypeScript 인터페이스로 정의한다 - 스타일링은 Tailwind CSS 클래스만 사용한다

• description: 이 Rule이 무엇을 위한 것인지 설명한다. AI가 언제 이 Rule을 참조할지 판단하는 근거로 사용된다.
• globs: 이 경로 패턴에 해당하는 파일이 컨텍스트에 포함될 때 Rule이 자동으로 활성화된다.
• alwaysApply: true로 설정하면 파일 위치와 무관하게 모든 AI 요청에 항상 적용된다.

적용 방식 네 가지

• Always (항상 적용): alwaysApply: true. 모든 AI 요청에 자동 포함된다. 프로젝트 전체 언어·스택 규칙에 적합하다.
• Auto Attached (자동 첨부): globs 패턴과 일치하는 파일이 컨텍스트에 포함될 때 자동 활성화된다. 특정 폴더나 파일 유형별 규칙에 적합하다.
• Agent Requested (AI 판단 적용): description을 기반으로 AI가 필요하다고 판단할 때 참조한다. alwaysApply: false이고 globs도 없는 경우에 해당한다.
• Manual (수동 참조): 채팅에서 @규칙파일명으로 직접 호출한다. 특정 상황에서만 임시로 규칙을 적용하고 싶을 때 유용하다.

네 가지 방식을 적절히 조합하면 "모든 파일에 공통 적용"과 "특정 파일에만 조건부 적용"을 동시에 관리할 수 있다. 예를 들어 프로젝트 기본 언어·스택은 Always로 고정하고, API 라우트 규칙은 Auto Attached로 분리하면 AI가 불필요한 컨텍스트를 처리하는 부담을 줄일 수 있다.

처음부터 따라하기 — 첫 번째 Project Rule 만들기

아래 단계는 TypeScript + React 프로젝트를 예시로 한다. 각자의 환경에 맞게 내용을 수정해 적용하면 된다.

1단계: 디렉터리와 파일 생성

터미널에서 프로젝트 루트 위치에서 실행한다.

mkdir -p .cursor/rules touch .cursor/rules/project-base.mdc

2단계: 기본 Rule 작성

.cursor/rules/project-base.mdc 파일을 열고 아래 내용을 작성한다.

--- description: 이 프로젝트의 기본 코딩 규칙 alwaysApply: true --- # 프로젝트 기본 규칙 ## 언어 및 스택 - 언어: TypeScript 5.x (strict 모드) - 프레임워크: Next.js 14 (App Router) - 스타일링: Tailwind CSS v3 ## 코드 스타일 - 컴포넌트는 함수형으로만 작성한다 - export는 named export를 기본으로 한다 - 비동기 처리는 async/await를 사용한다 ## 네이밍 규칙 - 컴포넌트 파일명: PascalCase (예: UserCard.tsx) - 유틸리티 함수 파일명: camelCase (예: formatDate.ts) - 상수: UPPER_SNAKE_CASE

3단계: 파일 유형별 Rule 추가 (Auto Attached)

API 라우트 폴더에만 적용하는 Rule을 별도

파일로 관리한다.

--- description: API 라우트 작성 규칙 globs: ["src/app/api/**/*.ts"] alwaysApply: false --- # API Route 규칙 - 모든 응답은 NextResponse.json()으로 반환한다 - 에러 응답에는 반드시 status 코드와 message 필드를 포함한다 - 입력값 검증은 라우트 핸들러 첫 줄에서 처리한다

4단계: Cursor에서 Rule 확인

Cursor 좌측 사이드바에서 Settings > Cursor Settings > Rules 탭을 열면 현재 프로젝트에 로드된 Rules 목록을 확인할 수 있다. alwaysApply: true 규칙은 활성 상태로 표시된다.

5단계: 실제 동작 검증

Rule 작성 후에는 실제로 작동하는지 반드시 확인해야 한다. Cursor 채팅창에 "간단한 버튼 컴포넌트를 만들어줘"라고 입력하고, 생성된 코드가 Rules에 명시한 방식(함수형, named export, Tailwind 스타일링)을 따르는지 검토한다. Rule이 적용되지 않은 것처럼 보인다면 alwaysApply 설정을 확인하거나, Cursor를 재시작해 Rules 캐시를 갱신한다.

언제 써야 하고, 언제 쓰지 말아야 하는가

Rules가 효과적인 경우

• 팀 단위 또는 장기 프로젝트에서 코딩 컨벤션을 AI에게 반복 설명하는 비용을 줄이고 싶을 때
• 특정 폴더(API, 컴포넌트, 테스트)마다 다른 기준을 적용해야 할 때
• 도메인 용어나 프로젝트 고유 패턴을 AI에게 지속적으로 반영해야 할 때
• 팀원이 늘어날수록 코드 스타일 편차가 커지는 문제를 AI 레벨에서 미리 방지하고 싶을 때

Rules가 효과적이지 않은 경우

• 너무 많은 내용을 한 파일에 넣는 경우: Rules 파일이 1,000줄을 넘어가면 AI가 관련 내용을 정확히 참조하기 어렵다. 역할별로 파일을 분리하는 것을 권장한다.
• 자주 바뀌는 정책을 Rules로 관리하는 경우: Rules는 안정된 컨벤션용이다. 매주 바뀌는 비즈니스 로직을 Rules에 넣으면 관리 부담이 오히려 커진다.
• 단발성 프로젝트: 한 번 쓰고 버리는 스크립트나 실험용 코드라면 Rules 작성 시간이 낭비가 된다.

Rules는 AI에게 줄 수 있는 가장 저렴한 컨텍스트다. 단, 컨텍스트는 길수록 좋은 것이 아니라 정확할수록 좋은 것이다. 짧고 명확한 Rules가 길고 모호한 Rules보다 일관성 향상에 실질적으로 기여한다.

Rules 파일을 어떻게 구성할지 막막하다면 "지금 AI에게 가장 많이 반복 설명하는 내용"부터 Rules로 옮기는 것이 가장 빠른 시작점이다. 반복 설명을 줄이는 것 자체가 곧 생산성 향상으로 이어진다.

다음으로 배울 것

Cursor Rules의 기초를 익혔다면 다음 단계로 넘어갈 수 있다.

• MCP(Model Context Protocol) 연동: Rules와 MCP를 함께 사용하면 AI가 외부 데이터(Notion, GitHub 등)를 참조하면서 프로젝트 규칙도 지킬 수 있다.
• Cursor Docs 인덱싱: @Docs 기능으로 공식 문서를 AI 컨텍스트에 추가하면 최신 API 사용법까지 정확하게 반영된다.
• Rules 버전 관리: Rules 파일을 프로젝트 git 저장소에 함께 커밋하면 팀원

AI 코딩 도구의 일관성 문제는 도구의 한계가 아니라 설정의 문제다. Rules를 통해 AI에게 일관된 컨텍스트를 제공하는 순간, 도구의 신뢰성은 크게 달라진다.