Claude Code의 CLAUDE.md는 Cursor의 기존 .cursorrules와 달리 프로젝트 규칙을 강제합니다. alwaysApply: true를 사용하여 구조화하고 도메인별로 분리하세요.

무엇이 변했는가 — .cursorrules의 유산과 Claude Code의 접근 방식

Cursor의 .cursorrules 파일은 에이전트 모드(Agent Mode)에서 조용히 무시됩니다. 이는 Claude Code의 문제가 아닙니다. Claude Code는 프로젝트 규칙을 위해 CLAUDE.md를 사용합니다. 하지만 Cursor에서 마이그레이션(migration) 중이라면 다음을 알아야 합니다: CLAUDE.md는 Claude Code의 에이전트 워크플로우(agentic workflows)에서 규칙을 강제할 수 있는 유일한 방법입니다.

Cursor의 .cursorrules는 일반 채팅에서는 작동하지만 에이전트 모드에서는 작동하지 않습니다. 최신 시스템은 YAML 프론트매터(frontmatter)가 포함된 .cursor/rules/*.mdc 파일을 사용합니다. Claude Code 사용자에게는 더 단순하고 강력한 대안인 CLAUDE.md가 있습니다.

사용자에게 미치는 영향 — 일상적인 Claude Code 사용에 대한 구체적 영향

만약 Claude Code의 동작을 가이드하기 위해 .cursorrules에 의존해 왔다면, 규칙 강제 효과를 전혀 얻지 못하고 있었을 것입니다. Claude Code는 .cursorrules를 완전히 무시합니다. 대신 프로젝트 루트(root)에 있는 CLAUDE.md를 사용합니다.

이것은 다음 현상들을 설명해 줍니다:

• Claude Code가 왜 계속 잘못된 프레임워크(framework)를 사용하는지
• 왜 실행 도중에 명명 규칙(naming conventions)이 무시되는지
• 왜 동일한 지침이 채팅에서는 작동하지만 에이전트 작업에서는 작동하지 않는지

해결책은 무엇일까요? 프로젝트 루트에 CLAUDE.md 파일을 생성하는 것입니다.

지금 바로 시도해보세요 — Claude Code를 위한 CLAUDE.md 구조화 방법

최소한의 작동 구조:

your-project/
└── CLAUDE.md          ← 전역 규칙(global rules), 항상 로드됨
└── .claude/
...

전역 규칙 (Global Rules - CLAUDE.md)

---
description: "모든 에이전트 작업을 위한 핵심 프로젝트 규칙"
alwaysApply: true
...

핵심 필드는 alwaysApply: true입니다. 이 설정이 없으면 Claude Code가 규칙 파일을 완전히 건너뛸 수 있습니다.

컨텍스트별 규칙 (Context-Specific Rules - .claude/rules/backend.md)

---
description: API 라우트 및 서버 측 코드를 위한 규칙
globs: ["app/api/**", "lib/server/**"]
...

globs 필드는 Claude Code에게 이 파일을 언제 로드할지 알려줍니다. 에이전트가 app/api/users/route.ts를 건드리면, 자동으로 백엔드(backend) 규칙을 가져옵니다.

흔한 마이그레이션 실수

1. 글로벌 규칙에 alwaysApply: false 설정 — alwaysApply: true 설정이 없으면, Claude Code는 파일 글로브 (file glob)가 일치할 때만 규칙을 로드합니다. 글로벌 규칙에는 명시적인 옵트인 (opt-in)이 필요합니다.

2. .cursorrules와 CLAUDE.md 파일을 모두 유지하는 경우 — 혼합된 상태는 일관되지 않은 동작을 유발합니다. 마이그레이션이 완료되면 .cursorrules를 삭제하세요.

3. 하나의 거대한 CLAUDE.md 파일 — 규칙 파일은 컨텍스트 (context)별로 평가됩니다. 도메인별로 분리하세요: 항상 적용되는 글로벌 규칙, 언어별 규칙, 프레임워크별 규칙, 금지 목록 (no-go lists).

4. YAML 프론트매터 (YAML frontmatter) 누락 — 상단의 --- 블록이 반드시 필요합니다. 프론트매터가 없는 CLAUDE.md는 로드에 조용히 실패할 수 있습니다.

빠른 마이그레이션 체크리스트

• 프로젝트 루트에 CLAUDE.md 생성
• 글로벌 규칙에 alwaysApply: true 설정
• 중요한 .cursorrules 내용을 CLAUDE.md로 복사
• 도메인 규칙을 globs를 포함한 별도의 .claude/rules/*.md 파일로 분리
• .cursorrules를 삭제하거나 .cursorrules.bak로 이름 변경
• Claude Code 에이전트 작업을 실행하고 규칙 적용 여부 확인

이것이 Claude Code 사용자에게 중요한 이유

Cursor의 .cursorrules 지원 중단은 대부분의 튜토리얼에서 조용히 이루어지며 문서화되어 있지 않습니다. 만약 Claude Code 에이전트가 계속해서 규칙을 무시한다면, 거의 확실히 이 문제 때문일 것입니다. Claude Code의 CLAUDE.md 시스템은 더 투명하고 강력합니다. 이를 올바르게 사용하세요.

출처: dev.to

원문 게시지: gentic.news