Cursor Rules 완벽 가이드: AI가 규칙에 맞는 코드를 생성하게 만드는 법(실전 설정 포함)

Cursor가 방금 생성한 코드를 바라보며 손가락을 Enter 키 위에 올린 채 멈췄습니다. 벌써 세 번째였습니다.

처음에는 변수를 var로 선언했고, 두 번째에는 클래스 컴포넌트로 바꾸더니, 이번에는 TypeScript 타입을 전부 지운 데다 any까지 잔뜩 추가했습니다. 결국 코드를 지우고 직접 작성하기로 했습니다.

그 순간 깨달았습니다. AI가 충분히 똑똑하지 않은 게 아니라, 애초에 ‘내 규칙’을 알려 주지 않았던 겁니다.

Cursor를 처음 사용할 때는 AI가 좋은 코드가 무엇인지 ‘알아서 알 것’이라고 생각했습니다. 하지만 팀원이 “Cursor가 생성한 컴포넌트는 왜 우리 팀 스타일과 완전히 달라요?”라고 불평한 뒤에야 AI에도 명확한 규칙이 필요하다는 사실을 알게 됐습니다.

이 글은 바로 그 문제를 해결하는 방법을 설명합니다. 5분만 들여 Cursor Rules를 설정하면 이후 AI가 생성하는 코드는 프로젝트 규칙에 맞게 바뀝니다. 잘못된 기술 스택을 사용하거나 코딩 스타일을 어기는 일도 줄어듭니다.

Cursor Rules란 무엇이며 왜 필요한가요?

Cursor Rules의 본질: AI를 위한 규칙 정하기

간단히 말해 Cursor Rules는 AI에 코딩 규칙을 알려 주는 설정 파일입니다.

회사가 신입 직원에게 ‘개발 안내서’를 나눠 주는 것과 비슷합니다. 안내서에는 어떤 기술 스택을 사용하는지, 코드 이름은 어떻게 짓는지, 파일은 어떻게 구성하는지 적혀 있습니다. Cursor Rules도 마찬가지로 AI에 ‘입사 교육 안내서’를 제공합니다.

작동 방식은 꽤 단순합니다. Cursor와 대화할 때 규칙 파일의 내용이 프롬프트에 자동으로 추가됩니다. AI는 이 규칙을 보고 ‘이 프로젝트에서는 React Hooks를 사용하고 클래스 컴포넌트는 쓰면 안 되는구나’라고 이해한 뒤 규칙에 맞는 코드를 생성합니다.

Rules를 설정하지 않으면 어떻게 될까요? 직접 겪은 시행착오

Cursor로 처음 프로젝트를 만들었을 때는 대단한 도구를 찾았다고 생각했습니다. AI가 코드를 정말 빠르게 작성했기 때문입니다. 하지만 사흘 뒤 큰 문제가 보이기 시작했습니다.

코드 스타일이 완전히 뒤죽박죽이었습니다. 어떤 파일은 camelCase, 다른 파일은 PascalCase, 또 몇몇 파일은 스네이크 표기법인 snake_case를 사용했습니다. 저조차 어떤 규칙이 어디에 적용됐는지 기억하기 어려웠습니다.

기술 스택도 잘못 사용했습니다. 함수 컴포넌트를 원했는데 Cursor는 class Component extends React.Component를 잔뜩 생성했습니다. ‘Hooks를 사용해 달라’고 말해도 다음 파일에서는 다시 원래 방식으로 돌아갔습니다.

프로젝트 규칙도 어겼습니다. 팀 규칙상 모든 함수에 주석을 작성해야 했지만 Cursor가 생성한 코드는 말끔했습니다. 주석이 한 줄도 없었습니다. 오류 처리 역시 반드시 try-catch를 사용해야 했지만 AI는 아무 처리 없이 API를 직접 호출했습니다.

그 뒤 이틀 동안 코드를 리팩터링하느라 손이 아플 정도였습니다.

Rules를 설정한 뒤에는? 기대 이상의 효과

그 후 5분을 들여 .cursorrules 파일을 만들고 다음 내용을 분명히 적었습니다.

• 기술 스택은 React 18 + TypeScript
• 함수 컴포넌트와 Hooks만 사용
• 이름은 모두 camelCase로 통일
• 타입 정의는 필수이며 any는 금지

결과가 어땠을까요?

그날부터 Cursor가 생성하는 모든 컴포넌트가 규칙을 따르기 시작했습니다. 코드 일관성은 적어도 80% 높아졌고, code review에 쓰는 시간은 절반으로 줄었습니다. 팀원들은 “어떻게 Cursor가 이렇게 말을 잘 듣게 만들었어요?”라고 물었습니다.

설정한 보람이 확실했습니다.

데이터는 거짓말하지 않습니다. 커뮤니티 모범 사례에 따르면 Rules를 적절히 설정하면 코드 일관성을 크게 높이고 이후 리팩터링 비용을 줄일 수 있습니다. GitHub의 awesome-cursorrules 저장소가 이미 2,000개 이상의 star를 받았다는 사실만 봐도 개발자에게 실제로 필요한 기능임을 알 수 있습니다.

Cursor Rules 설정 방법(2026년 최신)

먼저 알아둘 점: 기존 방식과 새 방식의 변화

인터넷에서 Cursor Rules 튜토리얼을 검색하면 두 가지 설명을 볼 수 있습니다. 어떤 글은 .cursorrules 파일을 사용하라고 하고, 다른 글은 .cursor/rules 디렉터리를 사용하라고 합니다. 둘 다 맞지만 적용된 시점이 다릅니다.

기존 방식(2025년 이전):
프로젝트 루트에 .cursorrules 파일 하나를 직접 만들고 모든 규칙을 그 안에 작성합니다. 단순하고 직관적입니다.

새 방식(2026년 권장):
프로젝트 루트에 .cursor/rules 디렉터리를 만든 뒤 여러 .mdc 파일을 넣습니다. 각 파일이 서로 다른 규칙 범주를 담당할 수 있습니다.

공식적으로는 이미 새 방식으로 이전할 것을 권장하고 있습니다. 새 방식이 더 유연하기 때문입니다. 기능별로 규칙을 분리할 수도 있고 서로 다른 적용 범위를 지정할 수도 있습니다. 기존 방식도 지금은 사용할 수 있지만 향후 버전에서 폐기될 예정입니다.

제가 권하는 방법은 간단합니다. 새 프로젝트라면 바로 새 방식을 사용하세요. 기존 프로젝트라면 여유가 있을 때 이전해도 늦지 않습니다.

두 가지 규칙 수준: 전역 vs 프로젝트

Cursor는 두 단계의 규칙을 지원합니다. 두 규칙의 차이를 이해하는 것이 중요합니다.

User Rules(전역 규칙)

개인 코딩 선호 사항이며 모든 프로젝트에 적용됩니다.

설정 경로: File → Preferences → Cursor Settings → Rules → User Rules

적합한 상황: 여러 프로젝트에 공통으로 적용하는 규칙입니다. 예를 들면 다음과 같습니다.

• ‘모든 프로젝트에서 TypeScript를 사용한다’
• ‘var는 사용하지 않고 const 또는 let으로 통일한다’
• ‘모든 비동기 작업에는 async/await를 사용하고 .then()은 사용하지 않는다’

개인의 ‘코드 취향’을 설정하는 항목이라고 이해하면 됩니다.

Project Rules(프로젝트 규칙)

개별 프로젝트를 위한 규칙이며 현재 프로젝트에만 적용됩니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

설정 방법:

1. 프로젝트 루트에 .cursor 폴더를 만듭니다.
2. .cursor 안에 rules 폴더를 만듭니다.
3. rules 안에 frontend.mdc나 typescript-rules.mdc 같은 .mdc 파일을 만듭니다.

적합한 상황: 프로젝트별 기술 스택과 규칙입니다. 예를 들면 다음과 같습니다.

• ‘이 프로젝트는 Next.js 14 + TypeScript + Tailwind CSS를 사용한다’
• ‘API 인터페이스는 RESTful 규칙으로 통일한다’
• ‘컴포넌트 파일은 components/ 디렉터리에 두고 PascalCase로 이름을 짓는다’

우선순위는 명확합니다. 프로젝트 규칙 > 전역 규칙입니다. 두 규칙이 충돌하면 프로젝트 규칙을 따릅니다.

규칙 적용 범위: 지나치게 넓게 적용하지 않기

2026년 새 버전의 중요한 기능은 규칙이 언제 적용되는지 제어할 수 있다는 점입니다.

.mdc 파일에서는 다음과 같은 적용 범위를 설정할 수 있습니다.

Always(항상 적용): 어떤 작업을 하든 규칙이 적용됩니다. ‘var 사용 금지’ 같은 핵심 규칙에 적합합니다. 다만 Always 규칙이 너무 많으면 AI 컨텍스트가 복잡해지므로 신중하게 사용하세요.

Auto Attached(자동 첨부): 파일 유형에 따라 자동으로 적용됩니다. 예를 들어 ‘.tsx 파일에는 React 규칙 자동 적용’, ‘.py 파일에는 Python 규칙 자동 적용’처럼 설정할 수 있습니다. 제가 가장 추천하는 방식입니다.

Agent Requested(AI가 판단): 대화 내용에 따라 AI가 규칙이 필요한지 결정합니다. 선택적인 보조 규칙에 적합합니다.

Manual(수동 호출): Cursor에 해당 규칙을 사용하라고 명시했을 때만 적용됩니다. ‘성능 최적화 전용 규칙’이나 ‘테스트 코드 규칙’ 같은 특수한 상황에 적합합니다.

제 경험상 Auto Attached 80%, Always 10%, 나머지 10%는 상황에 따라 선택하는 구성이 좋습니다.

2026년 1월의 새 기능: /rules 명령

2026년 1월 8일 Cursor는 CLI 업데이트를 통해 매우 유용한 /rules 명령을 새로 추가했습니다.

이제 Cursor 터미널에서 /rules를 직접 입력하면 폴더를 일일이 찾지 않아도 규칙 파일을 빠르게 만들고 편집할 수 있습니다. 규칙을 자주 조정하는 사람이라면 시간을 꽤 절약할 수 있는 기능입니다.

자세한 사용법은 Cursor 공식 포럼의 업데이트 공지에서 확인할 수 있습니다.

효과적인 Cursor Rules를 작성하는 방법

가장 중요한 부분입니다. 규칙을 얼마나 잘 작성하느냐에 따라 Cursor가 제대로 따를 수 있는지가 결정됩니다.

규칙 내용의 세 가지 주요 범주

규칙을 설정할 때는 세 가지 관점으로 나눠 작성하는 것이 좋습니다.

A. 기술과 아키텍처

먼저 AI에 어떤 프로젝트인지 알려 줍니다.

프로젝트 기술 스택:
- 프론트엔드: React 18 + TypeScript 5.3
- 상태 관리: Zustand
- 스타일: Tailwind CSS 3.4
- 빌드 도구: Vite 5.0
- Node.js 버전: 18+

아키텍처 규칙도 명확히 설명해야 합니다.

아키텍처 규칙:
- 프론트엔드와 백엔드 분리
- API는 RESTful 스타일 사용
- 폴더 구조:
  - components/ 재사용 컴포넌트 저장
  - pages/ 페이지 컴포넌트 저장
  - utils/ 유틸리티 함수 저장
  - hooks/ 사용자 정의 Hooks 저장

왜 이렇게 자세히 써야 할까요?

직접 시행착오를 겪었습니다. 예전에는 ‘React 사용’이라고만 적었더니 Cursor가 가끔은 React 16 방식으로, 가끔은 React 18 방식으로 코드를 생성했습니다. 버전 번호를 분명히 적은 뒤 문제가 사라졌습니다.

B. 코드 규칙

코드 스타일을 통일하는 핵심 부분입니다.

코드 규칙:

명명 규칙:
- 컴포넌트 이름: PascalCase (예: UserProfile)
- 파일 이름: kebab-case (예: user-profile.tsx)
- 변수와 함수: camelCase (예: getUserData)
- 상수: UPPER_SNAKE_CASE (예: MAX_RETRY_COUNT)

코드 스타일:
- 함수 컴포넌트만 사용하고 클래스 컴포넌트는 사용하지 않음
- const를 우선하고 다음으로 let을 사용하며 var는 금지
- 화살표 함수를 사용하고 this가 필요한 경우가 아니면 function 키워드는 사용하지 않음
- 모든 컴포넌트에 TypeScript 타입을 반드시 정의

파일 길이:
- 파일 하나는 300줄 이하
- 함수 하나는 50줄 이하

주석 요구 사항:
- 핵심 함수에는 반드시 JSDoc 주석 작성
- 복잡한 로직에는 반드시 인라인 주석 작성
- 주석에는 ‘무엇을’이 아니라 ‘왜’를 설명

C. 품질과 테스트

오류 처리:
- 모든 비동기 작업에 반드시 try-catch 사용
- API 호출 실패 시 사용자 친화적인 오류 메시지 제공
- 오류를 무시하지 말고 최소한 console.error로 기록

성능 최적화:
- 목록 렌더링에는 반드시 key 사용
- 큰 목록에는 가상 스크롤 사용
- 레이아웃 이동을 방지하도록 이미지의 너비와 높이를 반드시 지정

테스트 요구 사항:
- 유틸리티 함수에는 반드시 단위 테스트 작성
- 핵심 비즈니스 로직은 반드시 테스트로 검증

규칙 작성의 황금 원칙

원칙 1: 구체적이고 실행 가능하며 검증할 수 있게 작성하기

가장 중요한 원칙입니다.

❌ 잘못된 예시: ‘코드를 잘 작성하세요’, ‘모범 사례를 따르세요’, ‘성능에 유의하세요’

이런 규칙은 사실상 아무 말도 하지 않은 것과 같습니다. AI는 ‘모범 사례’가 구체적으로 어떤 사례를 말하는지 알 수 없습니다.

✅ 올바른 예시:

• ‘함수 컴포넌트를 사용하고 클래스 컴포넌트는 사용하지 마세요’
• ‘Props는 type 대신 interface로 정의하세요’
• ‘비동기 작업에는 .then() 대신 async/await를 사용하세요’

차이가 보이나요? 좋은 규칙은 모호한 조언이 아니라 바로 실행할 수 있는 지시입니다.

원칙 2: 500줄 이내로 유지하기

커뮤니티에서 권장하는 모범 사례입니다. 규칙이 너무 길면 AI가 이해하기 어렵고 컨텍스트 공간도 많이 차지합니다.

규칙 파일이 500줄을 넘었다면 다음과 같이 분리해야 합니다.

• frontend.mdc - 프론트엔드 관련 규칙
• backend.mdc - 백엔드 관련 규칙
• typescript.mdc - TypeScript 규칙
• testing.mdc - 테스트 관련 규칙

원칙 3: 설명만 하지 말고 예제 코드 사용하기

AI는 예시를 가장 잘 이해합니다.

❌ 설명만 있는 경우:

컴포넌트는 함수형으로 작성하고 타입을 정의해야 합니다.

✅ 예시를 제공하는 경우:

컴포넌트 예시:

interface UserCardProps {
  name: string;
  email: string;
}

export const UserCard = ({ name, email }: UserCardProps) => {
  return (
    <div className="user-card">
      <h3>{name}</h3>
      <p>{email}</p>
    </div>
  );
};

예시가 있으면 Cursor가 어떤 형태의 코드를 원하는지 정확히 알 수 있습니다. 특히 효과적인 방법입니다.

원칙 4: 가장 중요한 규칙을 앞에 배치하기

AI는 앞쪽에 있는 내용을 우선적으로 확인합니다. 따라서 다음 순서로 구성하세요.

1순위: 기술 스택과 버전

2순위: 코드 스타일

3순위: 파일 구성

마지막: 선택적 최적화 제안

자주 하는 실수와 피해야 할 함정

실수 1: 규칙이 너무 포괄적임

‘React 모범 사례를 따르세요.’ 어떤 모범 사례를 말하는 걸까요? 2016년 방식일까요, 2024년 방식일까요?

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

다음처럼 바꾸세요. ‘React Hooks를 사용하고, useState와 useEffect를 우선하며, 복잡한 상태에는 useReducer를 사용하세요.’

실수 2: 규칙끼리 충돌함

‘TypeScript를 반드시 사용한다’고 해 놓고 ‘any 타입 사용을 허용한다’고 하면 서로 모순됩니다.

AI는 충돌하는 규칙을 보면 혼란스러워하며 결국 둘 다 지키지 않을 수 있습니다.

실수 3: 버전을 지정하지 않음

React 16의 클래스 컴포넌트 방식과 React 18의 Hooks 방식은 크게 다릅니다. ‘React를 사용한다’고만 적으면 AI가 임의의 버전 방식을 선택할 수 있습니다.

반드시 React 18.2+, TypeScript 5.3+, Node.js 18+처럼 분명히 작성하세요.

실수 4: 규칙을 논문처럼 작성함

어떤 사람들은 규칙을 장황하게 쓰고, 왜 그렇게 해야 하는지 설명하며, 여러 이론적 근거까지 나열합니다.

그럴 필요가 없습니다. AI를 설득할 필요는 없으며 AI는 ‘무엇을 해야 하는지’만 알면 됩니다.

❌ ‘TypeScript는 정적 타입 검사를 제공하고 컴파일 단계에서 오류를 찾아 코드 품질을 높일 수 있으므로 선택했습니다…’(이후 300자 더 이어짐)

✅ ‘TypeScript를 사용하고 any 타입은 금지합니다.’

짧고 명확하게 작성하세요.

실전: React + TypeScript 프로젝트 규칙 설정하기

이론을 많이 설명하는 것보다 실제 예시 하나를 보는 편이 낫습니다.

다음 기술 스택으로 React + TypeScript 프로젝트를 만든다고 가정해 보겠습니다.

• React 18
• TypeScript 5.x
• Tailwind CSS 3.x
• Vite 5.x

팀의 규칙은 다음과 같습니다.

• 함수 컴포넌트만 사용
• 엄격한 타입 적용 및 any 금지
• 파일과 이름 규칙 통일
• 오류 처리 필수

이제 규칙 파일을 단계별로 설정해 보겠습니다.

Step 1: 규칙 파일 만들기

프로젝트 루트에서 다음 명령을 실행합니다.

mkdir -p .cursor/rules
cd .cursor/rules
touch react-typescript.mdc

Step 2: 기술 스택 정의하기

react-typescript.mdc를 열고 먼저 기술 스택을 명확히 작성합니다.

# React + TypeScript 프로젝트 규칙

## 기술 스택

- React 18.2+
- TypeScript 5.3+
- Tailwind CSS 3.4+
- Vite 5.0+
- Node.js 18+

## 의존성 관리

- 패키지 관리자: pnpm
- npm이나 yarn은 사용하지 않음

Step 3: 코드 스타일 규칙

이어서 코드를 작성하는 방식을 정의합니다.

## 코드 규칙

### 컴포넌트 규칙

- 함수 컴포넌트만 사용하고 클래스 컴포넌트는 금지
- 컴포넌트 이름은 PascalCase 사용
- 파일 이름은 kebab-case 사용
- 기본 내보내기 대신 명명된 내보내기 사용

예시:

// ❌ 잘못된 예시
export default function userProfile() { }

// ✅ 올바른 예시
export const UserProfile = () => { }

### TypeScript 규칙

- 모든 컴포넌트에 타입을 반드시 정의
- Props는 type 대신 interface 사용
- any는 금지하고 unknown 또는 구체적인 타입 사용
- 함수 반환 타입을 반드시 명시

예시:

// ✅ 올바른 컴포넌트 정의
interface UserCardProps {
  name: string;
  email: string;
  age?: number;
}

export const UserCard = ({ name, email, age }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded">
      <h3 className="text-lg font-bold">{name}</h3>
      <p className="text-gray-600">{email}</p>
      {age && <p>Age: {age}</p>}
    </div>
  );
};

### 명명 규칙

- 변수와 함수: camelCase
- 컴포넌트: PascalCase
- 상수: UPPER_SNAKE_CASE
- 파일 이름: kebab-case
- CSS 클래스 이름: Tailwind 유틸리티 클래스만 사용하고 사용자 정의 CSS는 작성하지 않음

### 비동기 처리

- 모든 비동기 작업에 async/await 사용
- .then() 체이닝 금지
- try-catch 오류 처리 필수

예시:

// ✅ 올바른 예시
const fetchUserData = async (userId: string): Promise<User> => {
  try {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
};

Step 4: 파일 구성 규칙

## 파일 구성

### 디렉터리 구조

src/
├── components/     # 재사용 컴포넌트
├── pages/          # 페이지 컴포넌트
├── hooks/          # 사용자 정의 Hooks
├── utils/          # 유틸리티 함수
├── types/          # TypeScript 타입 정의
├── services/       # API 호출
└── constants/      # 상수 정의

### 파일 이름

- 컴포넌트 파일: user-card.tsx
- 유틸리티 파일: format-date.ts
- 타입 파일: user.types.ts
- Hook 파일: use-user-data.ts

### 가져오기 순서

1. React 관련 항목
2. 서드파티 라이브러리
3. 프로젝트 내부 컴포넌트
4. 유틸리티 함수
5. 타입 정의
6. 스타일

Step 5: 품질 요구 사항

## 품질 요구 사항

### 오류 처리

- API 호출에는 반드시 try-catch 사용
- 오류 메시지는 사용자 친화적으로 작성
- 오류 로그 기록

### 성능 최적화

- 목록 렌더링에는 반드시 key 속성 사용
- 렌더링 함수 안에서 새 객체나 함수를 만들지 않음
- React.memo로 불필요한 재렌더링 최적화
- 이미지에는 반드시 width와 height 지정

### 코드 품질

- 파일 하나는 300줄 이하
- 함수 하나는 50줄 이하
- 복잡한 로직에는 반드시 주석 작성
- 핵심 함수에는 반드시 JSDoc 주석 작성

Step 6: 완성된 규칙 파일

위 내용을 합치면 .cursor/rules/react-typescript.mdc 규칙 파일이 완성됩니다.

이 파일을 바탕으로 프로젝트 요구 사항에 맞게 조정할 수 있습니다. 예를 들면 다음과 같습니다.

• Redux를 사용한다면 Redux 규칙 추가
• React Query를 사용한다면 데이터 가져오기 규칙 추가
• 특별한 비즈니스 규칙이 있다면 해당 규칙 추가

효과 테스트하기

설정을 마친 뒤 Cursor에 사용자 카드 컴포넌트를 만들게 해 보세요.

프롬프트: ‘사용자 이름, 이메일, 프로필 사진을 표시하는 사용자 카드 컴포넌트를 만들어 주세요.’

규칙 설정 전에는 Cursor가 다음과 같은 코드를 생성할 수 있습니다.

export default function UserCard(props) {
  return <div>...</div>
}

규칙 설정 후에는 다음과 같이 생성됩니다.

interface UserCardProps {
  name: string;
  email: string;
  avatarUrl: string;
}

export const UserCard = ({ name, email, avatarUrl }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded shadow">
      <img src={avatarUrl} alt={name} className="w-16 h-16 rounded-full" width="64" height="64" />
      <h3 className="text-lg font-bold mt-2">{name}</h3>
      <p className="text-gray-600">{email}</p>
    </div>
  );
};

보이는 것처럼 모든 규칙을 따릅니다.

• ✅ 함수 컴포넌트
• ✅ TypeScript 타입 정의
• ✅ 명명된 내보내기
• ✅ Tailwind 스타일
• ✅ 이미지 너비와 높이 속성

한 번에 원하는 결과를 얻어 다시 작업할 필요가 없습니다.

고급 활용법과 자주 묻는 질문

규칙 우선순위: 어떤 규칙을 따를까요?

여러 단계의 규칙을 설정하면 충돌이 발생할 수 있습니다. Cursor의 규칙 우선순위는 다음과 같습니다.

프로젝트 규칙 > 전역 규칙

전역 규칙에서 ‘작은따옴표 사용’을 요구하지만 프로젝트 규칙에서는 ‘큰따옴표 사용’을 요구한다면 Cursor는 프로젝트 규칙을 따릅니다.

하위 디렉터리 규칙 > 상위 디렉터리 규칙

프로젝트 구조가 다음과 같다고 가정해 보겠습니다.

project/
├── .cursor/rules/general.mdc
└── frontend/
    └── .cursor/rules/react.mdc

frontend/ 디렉터리에서 작업할 때는 react.mdc의 우선순위가 더 높습니다.

수동 호출 > 자동 적용

대화에서 특정 규칙을 명시적으로 언급하면 적용 범위가 Manual이더라도 해당 규칙을 우선적으로 고려합니다.

여러 규칙 파일 관리하기: 효과적으로 분리하는 법

프로젝트가 복잡해지면 규칙 파일 하나로는 부족할 수 있습니다. 저는 다음과 같이 분리합니다.

.cursor/rules/
├── core.mdc              # 핵심 기술 스택(Always)
├── frontend.mdc          # 프론트엔드 규칙(Auto Attached: *.tsx, *.ts)
├── backend.mdc           # 백엔드 규칙(Auto Attached: *.py, *.go)
├── testing.mdc           # 테스트 규칙(Auto Attached: *.test.*)
└── performance.mdc       # 성능 최적화(Manual)

각 파일이 서로 다른 영역을 담당해 구조가 명확합니다.

디버깅 팁: 규칙이 적용되지 않으면 어떻게 하나요?

문제 1: 규칙이 적용됐는지 알 수 없음

Cursor의 Composer나 Chat을 열고 ‘어떤 규칙을 확인했나요?’라고 물어보세요.

Cursor는 현재 로드된 규칙 파일을 알려 줍니다. 작성한 규칙이 표시되지 않는다면 다음 원인을 확인하세요.

• 경로가 잘못되었을 수 있음
• 적용 범위 설정이 잘못되었을 수 있음
• 파일 형식에 문제가 있을 수 있음

문제 2: 규칙 충돌

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

두 규칙이 서로 모순되면 Cursor가 두 규칙 모두 따르지 않을 수 있습니다.

해결 방법:

1. 규칙 파일을 확인해 충돌 지점을 찾습니다.
2. 우선순위를 명확히 하고 낮은 우선순위 규칙을 삭제합니다.
3. 또는 높은 우선순위 규칙에 ‘다른 규칙을 재정의한다’고 명시합니다.

문제 3: AI가 규칙을 따르지 않음

규칙을 분명히 작성했는데도 Cursor가 제멋대로 행동할 때가 있습니다.

가능한 원인은 다음과 같습니다.

1. 규칙이 너무 모호함: 구체적인 지시로 바꿉니다.
2. 규칙이 너무 김: AI가 뒤쪽 내용을 무시할 수 있으므로 중요한 규칙을 앞에 배치합니다.
3. 규칙과 프롬프트가 충돌함: 대화에서는 ‘클래스 컴포넌트 사용’을 요구했지만 규칙은 ‘함수 컴포넌트 사용’을 요구한다면 AI는 대화 내용을 우선할 수 있습니다.

해결 방법:

• 규칙을 다시 작성하고 예제 코드를 추가합니다.
• 대화에서 ‘프로젝트 규칙에 따라 작성해 주세요’라고 명시합니다.
• 규칙을 Auto Attached에서 Always로 바꿉니다.

미리 만들어진 규칙 활용하기: 선구자의 경험 빌리기

처음부터 직접 규칙을 작성하고 싶지 않다면 커뮤니티에서 제공하는 다양한 리소스를 활용할 수 있습니다.

awesome-cursorrules

GitHub에서 가장 인기 있는 Cursor Rules 저장소로, 2,000개 이상의 star를 받았습니다. 다음 항목을 지원합니다.

• React, Vue, Angular 등 프론트엔드 프레임워크
• Python, Go, Java 등 백엔드 언어
• Next.js, Astro, Nuxt 등 풀스택 프레임워크
• TypeScript, 테스트, Docker 등 전문 규칙

필요한 규칙 파일을 복사한 뒤 조금만 조정하면 바로 사용할 수 있습니다.

awesome-cursorrules-zh

중국어 개발자를 위해 최적화한 규칙 라이브러리입니다. 특히 React와 FastAPI 규칙을 하나의 풀스택 프로젝트 규칙으로 결합하는 것과 같은 ‘통합 규칙’ 예시를 제공합니다.

cursor.directory

웹에서 규칙을 미리 보고 복사할 수 있는 온라인 규칙 라이브러리입니다. 30개 이상의 주요 프레임워크를 다룹니다.

dotcursorrules.com

다양한 실전 사례와 모범 사례를 소개하는 또 다른 온라인 리소스입니다.

제가 권하는 방법은 커뮤니티 규칙으로 시작해 일정 기간 사용한 뒤 프로젝트 요구 사항에 맞게 조정하는 것입니다. 처음부터 직접 작성하느라 시간을 낭비할 필요는 없습니다.

팀 협업: 규칙을 팀 자산으로 만들기

팀으로 개발한다면 규칙을 버전 관리에 포함하는 것이 좋습니다.

1. Git에 커밋하기

.cursor/rules 디렉터리를 코드 저장소에 커밋합니다.

git add .cursor/rules
git commit -m "Add Cursor rules for project standards"

그러면 팀 구성원이 코드를 가져온 뒤 Cursor가 프로젝트 규칙을 자동으로 로드해 모든 구성원의 AI 동작이 일관되게 유지됩니다.

2. 신규 구성원 교육

프로젝트 README에 다음 내용을 추가합니다.

## Cursor로 개발하기

이 프로젝트에는 `.cursor/rules` 디렉터리에 Cursor Rules가 설정되어 있습니다.

Cursor를 사용할 때 AI는 다음 규칙을 자동으로 따릅니다.
- React 18 + TypeScript
- 함수 컴포넌트 + Hooks
- Tailwind CSS 스타일
- 엄격한 타입 정의

규칙을 변경해야 한다면 먼저 팀과 논의하세요.

3. 정기 Review

기술 스택은 업데이트되고 규칙도 발전합니다. 분기마다 규칙 파일을 한 번씩 review하는 것이 좋습니다.

• 오래된 규칙이 있나요?
• 추가해야 할 새로운 모범 사례가 있나요?
• 팀 피드백 중 반영해야 할 규칙이 있나요?

규칙을 일회성 설정이 아닌 살아 있는 문서로 관리하세요.

결론

긴 내용을 한 문장으로 정리하면 AI가 제대로 일하려면 먼저 명확한 규칙을 정해야 합니다.

Cursor를 처음 사용했을 때 다음과 같은 경험을 하지 않았나요?

• 컴포넌트를 만들게 했더니 스타일이 제각각이었음
• TypeScript를 사용하라고 했는데 몰래 any를 추가함
• 코드가 지나치게 AI가 작성한 것처럼 보여 사람이 쓴 코드와 달랐음

Cursor의 잘못이 아닙니다. 우리가 ‘우리의 규칙’을 알려 주지 않았기 때문입니다.

이제 해야 할 일을 알게 됐습니다.

1. 규칙 파일 만들기 — 새 프로젝트는 .cursor/rules를 사용하고, 기존 프로젝트는 우선 .cursorrules를 사용할 수 있습니다.
2. 기술 스택 명확히 작성하기 — 버전 번호, 프레임워크, 도구 체인을 구체적으로 작성할수록 좋습니다.
3. 코드 규칙 정의하기 — 명명 방식, 스타일, 오류 처리 방법을 정하고 예제 코드를 제공합니다.
4. 규칙 길이 관리하기 — 500줄 이내로 유지하고 필요하면 파일을 분리합니다.
5. 지속적으로 개선하기 — 규칙은 일회성 설정이 아니며 프로젝트 변화에 따라 수정해야 합니다.

지금 바로 시작하세요.

• 아직 규칙을 설정하지 않았다면 5분을 들여 첫 번째 규칙 파일을 만드세요.
• 이미 규칙이 있다면 너무 모호하지 않은지 확인하고 예제 코드를 추가하세요.
• 팀 프로젝트라면 규칙을 Git에 커밋해 모두가 함께 따르게 하세요.

한 달 뒤에는 다음과 같은 변화를 확인할 수 있습니다.

• Code review 시간이 절반으로 줄어듦
• 코드 스타일이 통일됨
• 신규 구성원의 적응 속도가 빨라짐
• AI가 실제로 든든한 조력자가 됨

마지막으로 처음부터 직접 규칙을 작성하지 않아도 되도록 몇 가지 리소스를 소개합니다.

• awesome-cursorrules - 2,000개 이상의 star를 받은 규칙 라이브러리
• awesome-cursorrules-zh - 중국어 개발자용 최적화 버전
• cursorrules.org - 온라인 규칙 라이브러리