대부분의 CLAUDE.md 베스트 프랙티스 글들은 템플릿을 제시하고 끝내지만, 지난주에 작성한 파일은 아마도 이미 무시당하고 있을 것입니다. 그리고 왜 무시되는지 모를 겁니다. 해결책은 "규칙을 더 추가하는 것"이 거의 절대 아닙니다. 보통은 반대입니다. 최근의 모든 클라이언트 프로젝트에서 Claude Code를 운영해본 결과, 이 9가지 규칙이 실제로 효과를 내는 것들입니다: Claude가 파일을 로드하는 방식에 맞춘 계층 구조, 어길 수 없는 명령어 예산, AGENTS.md 선택 결정, 그리고 Claude가 세션 중에 파일을 조용히 무시하는 여섯 가지 이유들입니다.
핵심 요점
- CLAUDE.md는 Claude Code의 컨텍스트에 로드되는 프로젝트 메모리입니다 — 200줄 이상이면 규칙들이 누락되기 시작합니다.
- 파일은 하향식으로 로드됩니다: 전역, 프로젝트 루트, 서브디렉터리(지연 로드), 그리고 CLAUDE.local.md(개인 설정, gitignore됨).
- Cursor나 Copilot도 함께 사용하면 AGENTS.md를 사용하세요. CLAUDE.md를 AGENTS.md로 심링크하면 이중 대상을 지원할 수 있습니다.
- Claude가 파일을 무시한다면 90% 경우 길이, 모호함, 또는 누락된 "이유"입니다.
CLAUDE.md가 실제로 하는 일 (그리고 왜 중요한가)
많은 팀들이 CLAUDE.md를 README처럼 작성합니다. 이것이 첫 번째 실수입니다. README는 훑어볼 수 있고 건너뛸 수 있는 인간을 위해 설명합니다. CLAUDE.md는 Claude Code에 의해 세션 시작 시 완전히 소비되며, 모든 줄이 토큰 비용을 발생시키고 준수에 영향을 줍니다. 이는 문서보다는 설정 파일이나 테스트 fixture 세트에 훨씬 더 가깝습니다.
또한 Claude를 조종하는 유일한 방법은 아닙니다. 훅은 결정적인 작업들(포맷팅, 커밋 차단)을 실행합니다. 스킬은 재사용 가능한 워크플로우를 번들로 제공합니다. CLAUDE.md는 그 사이에 자문 컨텍스트로 위치합니다 — Claude는 이를 평가하고, 때때로 이를 무시하며, 너무 많이 작성하면 틀림없이 부분을 잊습니다. 이 구분이 아래의 모든 것의 기초이며, CLAUDE.md가 더 광범위한 컨텍스트 엔지니어링 관행의 하나의 도구일 뿐 만능 해결책이 아닌 이유입니다.
규칙 #1: 문서가 아니라 코드처럼 취급하세요. 버전을 관리하세요. PR에서 검토하세요. 비대한 모듈을 리팩토링하듯이 정리하세요. Anthropic의 CLAUDE.md 가이드에 따르면, 이 파일은 시스템 명령어와 동일한 우선순위로 로드됩니다 — 이는 6개월 전의 낡은 규칙이 오늘도 여전히 모든 응답을 적극적으로 형성하고 있다는 의미입니다.
CLAUDE.md가 로드되는 방식: 4단계 계층 구조
계층 구조는 CLAUDE.md에서 가장 오해받는 부분이며, 상위 5개 검색 결과 중 0개가 깊이 있게 다룹니다. 내부에서 실제로 일어나는 일은 다음과 같습니다:
명확히 해야 할 두 가지 용어: 지연 로드(lazy loading)와 형제 격리(sibling isolation).
지연 로드는 서브디렉터리의 CLAUDE.md가 Claude가 실제로 그 디렉터리 내의 파일을 열 때까지 Claude의 컨텍스트에 들어가지 않음을 의미합니다. "로그인 버그를 수정하라"고 요청하고 Claude가 오직 backend/만 건드린다면, 당신의 frontend/CLAUDE.md는 절대 로드되지 않습니다. 이것은 좋습니다 — 컨텍스트 윈도우를 깨끗하게 유지합니다 — 하지만 항상 적용될 것으로 기대하고 중요한 규칙을 서브디렉터리에 넣는 팀들에게는 문제가 됩니다.
형제 격리는 그에 따른 결과입니다: frontend/CLAUDE.md와 backend/CLAUDE.md는 서로를 로드하지 않습니다. 그들은 프로젝트 루트에 있는 것만 공유합니다. 따라서 당신의 프론트엔드 규칙과 백엔드 규칙이 모순된다면, 그것은 괜찮습니다. 규칙을 공유해야 한다면, 루트 파일로 올려보내세요.
CLAUDE.local.md는 탈출구입니다. 이것은 로드되지만 커밋되지 않으며, "팀은 npm을 표준화했지만 나는 pnpm을 선호한다" 같은 오버라이드에 완벽합니다. 단점은: 자동으로 gitignore되지 않습니다. 직접 추가해야 합니다. 그것을 잊으면 당신의 개인 규칙을 팀의 저장소에 커밋하게 될 것입니다.
규칙 #4: 명령어를 Claude가 실제로 읽는 위치에 맞추세요. React 컴포넌트의 스타일 규칙은 루트가 아니라 frontend/CLAUDE.md에 속합니다. 데이터베이스 마이그레이션 규칙은 backend/에 속합니다. Anthropic 메모리 문서(2025년 11월 업데이트)는 이를 확인합니다 — 지연 로드 동작은 의도적이고 기본에 영향을 주는 것입니다.
CLAUDE.md에 무엇을 넣을 것인가 (그리고 무엇을 빼야 할 것인가)
여기 실제로 효과가 있는 최소한의 CLAUDE.md가 있습니다:
이제 대부분의 팀이 배포하는 안티패턴 버전과 비교해보세요:
두 번째 파일이 잘못된 것은 아닙니다. 단지 쓸모가 없을 뿐입니다. Claude는 이미 깨끗한 코드를 작성하고 싶어합니다. "일관성 있게 작성하라"는 것은 Claude가 어떤 패턴으로 일관성 있어야 하는지 알려주지 않습니다. Anthropic 엔지니어 Boris Cherny의 공개 예제들은 첫 번째 스타일에 크게 의존합니다 — 구체적인 명령어, 명명된 도구, 그리고 코드베이스 자체로는 명백하지 않은 결정들의 이유.
규칙 #2: 열망적이지 말고 구체적이세요. "깨끗한 코드를 작성하라"는 열망적입니다. "기본적으로 서버 컴포넌트; 진정으로 필요할 때만 'use client' 추가"는 검증 가능합니다.
규칙 #3: 모든 규칙이 중요한 이유를 설명하세요. "이유"는 군더더기가 아닙니다 — 이것이 Claude가 경계 사례를 결정하는 방식입니다. 이유가 있는 규칙("과도한 클라이언트 렌더링으로 인해 8초 LCP에 도달했다")은 유사한 상황으로 일반화됩니다. 이유가 없는 규칙은 컨텍스트가 바뀌는 순간 무시됩니다. 이 패턴은 Builder.io의 CLAUDE.md 가이드에도 문서화되어 있습니다.
Claude가 당신의 CLAUDE.md를 무시하는 이유는? 명령어 예산
최근 연구는 프로덕션 사용자들이 계속 발견하는 것을 확인합니다: 명령어 준수는 규칙 수와 비선형적으로 악화됩니다. 명령어 준수 역량에 관한 arxiv 논문 2507.11538은 규칙을 쌓을수록 규칙당 준수 정도가 떨어짐을 보여줍니다 — HumanLayer의 프로덕션 CLAUDE.md 분석도 동일한 발견을 반복합니다.
해석하면: 추가하는 모든 규칙이 다른 모든 규칙을 조금씩 덜 준수하게 만듭니다. 따라서 400줄 CLAUDE.md는 100줄짜리보다 4배 효과적이지 않습니다. 실제로 당신이 정말 신경 쓰는 규칙들이 3개월 전 금요일에 작성했던 것들로 희석되기 때문에 종종 덜 효과적입니다.
우리의 CLAUDE.md 파일에서는, 150줄 이후부터는 준수도가 눈에 띄게 떨어지기 시작합니다. 250줄쯤 되면 Claude가 전체 섹션을 건너뛰는 것을 봤습니다. 따라서 우리는 한계를 정합니다.
이것이 전부입니다. 이를 실행하세요. 200줄을 초과하면, 예산을 초과한 것입니다. 우리가 클라이언트에게 배포하는 규칙은 다음과 같습니다:
CLAUDE.md를 200줄 예산처럼 취급하세요. 모든 줄이 준수 비용을 들입니다. 중요한 곳에 사용하세요.
규칙 #1 강화: 간단하게 유지하세요. 200줄 미만. 500단어 미만의 밀도 있는 규칙. 자동화 규칙을 추가하고 싶다면("편집 후 항상 prettier 실행"), 그것들은 아마도 Claude Code 훅에 속할 것입니다 — 훅은 결정적이고 명령어 예산 토큰을 소비하지 않습니다.
CLAUDE.md, AGENTS.md, .cursorrules, 또는 copilot-instructions를 사용해야 하나요?
이것은 상위 5개 결과 중 0개가 실제로 답하는 질문입니다. 여기 행렬이 있습니다:
이중 대상 트릭은 한 줄입니다:
이것으로 끝입니다. 이제 Claude Code, Codex, 그리고 AGENTS.md를 인식하는 모든 도구는 동일한 파일을 읽습니다. 한 번 업데이트하면, 모든 에이전트가 이를 받습니다. AGENTS.md 스펙은 공개되어 있고 의도적으로 최소한입니다 — 그냥 통상적인 섹션을 가진 마크다운일 뿐입니다.
실제의 두 가지 걸림돌이 있습니다. 첫째: 팀에 Cursor 파워 유저가 있으면, Cursor의 .cursorrules는 다른 접근을 취합니다 — 단일 파일, 계층 구조 없음, 더 엄격한 형식. 일부 팀들은 둘 다 유지합니다: AGENTS.md는 공유 규칙, .cursorrules는 Cursor 특화 요약. 둘째: Copilot의 .github/copilot-instructions.md는 AGENTS.md로 폴백하지 않으므로, Copilot을 많이 사용하는 팀은 별도의 파일이 필요합니다.
처음부터 에이전트 스택을 선택하는 중이라면, Claude Code vs Cursor vs Copilot 분석이 하네스 수준에서 트레이드오프를 다룹니다. 간단히 말해: Claude Code의 계층 구조는 모노레포에 가장 강력하고, Cursor의 UX는 개인 작업에 승리하며, Copilot의 IDE 통합은 점진적 도입에 여전히 가장 부드럽습니다.
규칙 #9: 두 개 이상의 에이전트 CLI를 실행하면 AGENTS.md를 사용하세요. 같은 내용을 말하는 두 파일을 유지하지 마세요. 당신의 스택이 읽는 파일을 선택하고 나머지는 심링크하세요.
CLAUDE.md vs 훅 vs 스킬: 결정 삼각형
...