Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code 사용 시 규칙이 무시되는 문제를 해결하기 위해 CLAUDE.md 활용법을 설명합니다. Cursor의 .cursorrules와 달리 CLAUDE.md는 에이전트 워크플로우에서 규칙을 강제할 수 있는 핵심 도구입니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Claude Code의 CLAUDE.md는 Cursor의 기존 .cursorrules와 달리 프로젝트 규칙을 강제합니다. alwaysApply: true를 사용하여 구조화하고 도메인별로 분리하세요.
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의 동작을 가이드하기 위해 .cursorrules에 의존해 왔다면, 규칙 강제 효과를 전혀 얻지 못하고 있었을 것입니다. Claude Code는 .cursorrules를 완전히 무시합니다. 대신 프로젝트 루트(root)에 있는 CLAUDE.md를 사용합니다.
이것은 다음 현상들을 설명해 줍니다:
해결책은 무엇일까요? 프로젝트 루트에 CLAUDE.md 파일을 생성하는 것입니다.
최소한의 작동 구조:
your-project/
└── CLAUDE.md ← 전역 규칙(global rules), 항상 로드됨
└── .claude/
...
---
description: "모든 에이전트 작업을 위한 핵심 프로젝트 규칙"
alwaysApply: true
...
핵심 필드는 alwaysApply: true입니다. 이 설정이 없으면 Claude Code가 규칙 파일을 완전히 건너뛸 수 있습니다.
---
description: API 라우트 및 서버 측 코드를 위한 규칙
globs: ["app/api/**", "lib/server/**"]
...
globs 필드는 Claude Code에게 이 파일을 언제 로드할지 알려줍니다. 에이전트가 app/api/users/route.ts를 건드리면, 자동으로 백엔드(backend) 규칙을 가져옵니다.
글로벌 규칙에 alwaysApply: false 설정 — alwaysApply: true 설정이 없으면, Claude Code는 파일 글로브 (file glob)가 일치할 때만 규칙을 로드합니다. 글로벌 규칙에는 명시적인 옵트인 (opt-in)이 필요합니다.
.cursorrules와 CLAUDE.md 파일을 모두 유지하는 경우 — 혼합된 상태는 일관되지 않은 동작을 유발합니다. 마이그레이션이 완료되면 .cursorrules를 삭제하세요.
하나의 거대한 CLAUDE.md 파일 — 규칙 파일은 컨텍스트 (context)별로 평가됩니다. 도메인별로 분리하세요: 항상 적용되는 글로벌 규칙, 언어별 규칙, 프레임워크별 규칙, 금지 목록 (no-go lists).
YAML 프론트매터 (YAML frontmatter) 누락 — 상단의 --- 블록이 반드시 필요합니다. 프론트매터가 없는 CLAUDE.md는 로드에 조용히 실패할 수 있습니다.
CLAUDE.md 생성alwaysApply: true 설정.cursorrules 내용을 CLAUDE.md로 복사globs를 포함한 별도의 .claude/rules/*.md 파일로 분리.cursorrules를 삭제하거나 .cursorrules.bak로 이름 변경Cursor의 .cursorrules 지원 중단은 대부분의 튜토리얼에서 조용히 이루어지며 문서화되어 있지 않습니다. 만약 Claude Code 에이전트가 계속해서 규칙을 무시한다면, 거의 확실히 이 문제 때문일 것입니다. Claude Code의 CLAUDE.md 시스템은 더 투명하고 강력합니다. 이를 올바르게 사용하세요.
출처: dev.to
원문 게시지: gentic.news