Cursor에서 MDC 규칙 모범 사례 및 문제 해결

MDC(Markdown Configuration) 규칙은 Cursor가 코딩 표준, 프로젝트 규칙 및 AI 동작 지침을 시행하는 강력한 방법입니다. 올바르게 구성하면 코드 품질과 일관성을 크게 향상시킵니다. 이 가이드에서는 MDC 규칙을 생성, 구성 및 문제 해결하는 모범 사례를 다룹니다.

MDC 규칙이란 무엇인가?

MDC 규칙은 YAML 프론트 매터가 포함된 Markdown 파일로, 특정 파일이나 특정 컨텍스트에서 작업할 때 Cursor가 어떻게 동작해야 하는지 알려줍니다. 다음을 수행할 수 있습니다:

• 코딩 표준 시행
• 프로젝트 아키텍처 패턴 정의
• 문서 요구 사항 지정
• 특정 파일 유형에 대한 AI 동작 제어

파일 형식 요구 사항

MDC 규칙은 반드시 다음 정확한 형식을 따라야 합니다:

---
description: '규칙 설명을 여기에 입력'
globs: ['src/**/*.ts', 'tests/**/*.ts']
alwaysApply: false
---

# 규칙 제목

규칙 내용을 여기에 입력...

## 구체적인 지침

- 지침 1
- 지침 2

중요한 요구 사항

요구 사항	세부 사항
확장자	반드시 .mdc여야 합니다(.md 아님)
프론트 매터	--- 구분자 사이에 YAML 형식을 사용해야 합니다
위치	반드시 .cursor/rules/ 디렉터리에 있어야 합니다
globs	이 규칙이 적용되는 파일 패턴 배열
alwaysApply	부울값 - 파일 매칭 없이 적용할지 여부

명명 규칙

조직을 위해 번호가 매겨진 접두사 시스템을 사용합니다:

.cursor/rules/
  001-core-coding-standards.mdc
  002-typescript-conventions.mdc
  003-react-patterns.mdc
  100-api-design.mdc
  101-database-models.mdc
  200-testing-requirements.mdc
  201-documentation-rules.mdc

번호 체계

범위	카테고리	예시
001-099	핵심 규칙(모든 파일에 적용)	코딩 표준, 서식
100-199	통합 규칙(특정 도메인)	API, 데이터베이스, 인증
200-299	패턴/역할 규칙	테스트, 문서
300-399	기술별 규칙	React, Vue, Angular

효과적인 규칙 작성하기

구체적이고 실행 가능하게 작성

나쁜 예:

좋은 코드를 작성하세요.

좋은 예:

## 오류 처리

모든 비동기 함수는 try/catch 블록을 사용해야 합니다:

```typescript
async function fetchUser(id: string): Promise<User> {
  try {
    const response = await api.get(`/users/${id}`);
    return response.data;
  } catch (error) {
    logger.error(`Failed to fetch user ${id}`, error);
    throw new UserNotFoundError(id);
  }
}

### 예시 포함하기

항상 올바른 예와 잘못된 예를 모두 보여주세요:

```markdown
## 상태 관리

✅ 해야 할 것: 서버 상태에 React Query 사용
```typescript
const { data, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId)
});

❌ 하지 말아야 할 것: 데이터 가져오기에 useEffect 사용

// 이 패턴은 피하세요
useEffect(() => {
  fetchUser(userId).then(setUser);
}, [userId]);

### Glob 패턴 효과적으로 사용하기

```yaml
# 모든 TypeScript 파일에 적용
globs: ['**/*.ts', '**/*.tsx']

# 백엔드 코드에만 적용
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']

# 특정 테스트 파일에 적용
globs: ['**/*.test.ts', '**/*.spec.ts']

# 특정 파일 제외
globs: ['src/**/*.ts', '!src/generated/**']

일반적인 규칙 카테고리

1. 코드 스타일 규칙

---
description: '일관된 코드 스타일 시행'
globs: ['src/**/*.ts', 'src/**/*.tsx']
alwaysApply: true
---

# 코드 스타일 표준

## 가져오기
- 가져오기 그룹화: React, 외부 라이브러리, 내부 모듈, 타입
- src/ 모듈에는 절대 가져오기 사용
- 그룹 내에서 알파벳 순으로 정렬

## 명명
- 컴포넌트: PascalCase(UserProfile)
- 훅: 'use'로 시작하는 camelCase(useAuth)
- 상수: UPPER_SNAKE_CASE
- 파일: kebab-case(user-profile.tsx)

2. 아키텍처 규칙

---
description: '클린 아키텍처 패턴 시행'
globs: ['src/**/*.ts']
alwaysApply: false
---

# 아키텍처 지침

## 계층 종속성
- 도메인 계층: 외부 종속성 없음
- 애플리케이션 계층: 도메인에만 의존
- 인프라 계층: 애플리케이션에 의존

## 파일 구성

src/ domain/ # 비즈니스 로직, 엔티티 application/ # 유스케이스, DTO infrastructure/ # DB, API, 외부 서비스 presentation/ # UI 컴포넌트

3. 테스트 규칙

---
description: '테스트 요구 사항 및 패턴'
globs: ['**/*.test.ts', '**/*.test.tsx']
alwaysApply: true
---

# 테스트 표준

## 필수 테스트
- 모든 유틸리티 함수의 단위 테스트
- 모든 React 컴포넌트의 컴포넌트 테스트
- API 엔드포인트의 통합 테스트
- 중요한 사용자 흐름의 E2E 테스트

## 테스트 구조
AAA 패턴 따르기:
1. Arrange: 테스트 데이터 및 모의 설정
2. Act: 테스트할 함수 실행
3. Assert: 결과 검증

일반적인 문제 해결

문제 1: 변경 사항이 저장되지 않음

증상: .mdc 파일을 편집하고 저장했지만 Cursor가 변경 사항을 적용하지 않습니다.

해결 방법:

1. Cursor를 완전히 종료하세요(창을 닫는 것이 아니라 애플리케이션을 종료)
2. Cursor를 다시 엽니다
3. 변경 사항이 이제 적용되어야 합니다

이유: MDC 규칙은 Cursor가 시작될 때 캐시됩니다. 핫 리로드되지 않습니다.

문제 2: 규칙이 적용되지 않음

증상: 파일을 편집할 때 Cursor가 규칙을 무시합니다.

점검 목록:

• 파일 확장자가 .mdc입니다(.md 아님)
• 파일이 .cursor/rules/ 디렉터리에 있습니다
• 프론트 매터에 유효한 YAML 구문이 있습니다
• globs 패턴이 대상 파일과 일치합니다
• Markdown 콘텐츠에 구문 오류가 없습니다

디버그 명령:

# Cursor가 규칙을 인식하는지 확인
ls -la .cursor/rules/
# 파일 확장자 확인
file .cursor/rules/*

문제 3: 충돌하는 규칙

증상: 여러 규칙이 모순되는 지침을 제공합니다.

해결 순서:

1. 더 구체적인 glob 패턴을 가진 규칙이 우선합니다
2. alwaysApply: true인 규칙이 먼저 평가됩니다
3. 알파벳 순서에서 뒤에 있는 규칙이 앞의 규칙을 덮어씁니다

모범 사례: priority 필드 사용(지원되는 경우):

---
description: '높은 우선순위 규칙'
globs: ['src/**/*.ts']
priority: 100
---

문제 4: 규칙이 너무 김

증상: Cursor가 긴 규칙의 모든 지침을 따르지 않습니다.

해결 방법: 여러 개의 집중된 규칙으로 분할:

.cursor/rules/
  001-general-style.mdc       # 짧고 일반적인 지침
  002-error-handling.mdc      # 오류 처리 전용
  003-performance.mdc         # 성능 최적화

고급 기법

조건부 규칙

globs를 사용하여 코드베이스의 다른 부분에 다른 규칙을 적용합니다:

# 프론트엔드 규칙
globs: ['src/components/**/*.tsx', 'src/pages/**/*.tsx']
---
React hooks 패턴을 사용하세요. 함수형 컴포넌트를 선호하세요.

# 백엔드 규칙
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']
---
의존성 주입을 사용하세요. SOLID 원칙을 따르세요.

규칙 상속

기본 규칙을 생성하고 확장하세요:

---
description: '기본 TypeScript 표준'
globs: ['**/*.ts', '**/*.tsx']
alwaysApply: true
---

# 기본 TypeScript 규칙

- 엄격한 TypeScript 구성 사용
- 정당한 이유 없이 `any` 타입 사용 금지
- 객체 형태에는 `type`보다 `interface`를 선호

---
description: 'React 특정 확장'
globs: ['src/**/*.tsx']
alwaysApply: false
---

# React 규칙

기본 TypeScript 규칙에 추가로:
- 훅이 있는 함수형 컴포넌트 사용
- Props 인터페이스는 반드시 내보내기
- React.FC는 신중하게 사용(명시적 props 타이핑 선호)

변수를 사용한 동적 규칙

일부 고급 설정에서는 템플릿 변수를 지원합니다:

---
description: '프로젝트별 규칙'
globs: ['**/*.ts']
---

# 프로젝트 규칙

## API 기본 URL
사용: {{API_BASE_URL}}

## 인증
토큰 헤더: {{AUTH_HEADER_NAME}}

빠른 참조: MDC 규칙 템플릿

---
description: ''
globs: ['']
alwaysApply: false
---

# 제목

## 섹션 1
- 지침 1
- 지침 2

## 섹션 2
```typescript
// 예시 코드

참고 자료

• 문서 링크

## 관련 리소스

- [Cursor 규칙 효과적으로 사용하기](using-cursor-rules-effectively.mdx)
- [Cursor 규칙 모범 사례](best-practices-for-cursor-rules.mdx)
- [CursorRules 설정 가이드](cursorrules-setup-guide.mdx)