CLAUDE.md 완벽 정리

1. CLAUDE.md란 무엇인가

Claude Code의 각 세션은 새로운 컨텍스트 윈도우로 시작된다. 어제 대화에서 알려준 프로젝트 규칙도, 코딩 컨벤션도, 빌드 명령어도 — 다음 세션에서는 전부 사라진다.

CLAUDE.md는 이 문제를 해결하는 마크다운 파일이다. 세션이 시작될 때마다 Claude가 자동으로 읽어서 컨텍스트에 포함시킨다. 프로젝트 규칙, 아키텍처 결정, 워크플로우 등을 한 번 적어두면 매 세션마다 반복 설명할 필요가 없어진다.

다만 한 가지 명확히 할 것이 있다. CLAUDE.md는 **"강제(enforcement)"가 아니라 "컨텍스트(context)"**다. Claude가 읽고 따르려 하지만, 100% 준수를 보장하지는 않는다. 지침이 구체적이고 간결할수록 더 일관되게 따른다.

 

---

2. 생성 방법 — 세 가지 경로

① /init 명령어로 자동 생성

가장 빠른 시작 방법이다. Claude Code 세션에서 /init을 실행하면 Claude가 현재 코드베이스를 분석해서 CLAUDE.md 초안을 만들어준다. 사용 언어, 빌드 도구, 테스트 프레임워크, 프로젝트 구조 등을 파악해서 내용을 채운다.

이미 CLAUDE.md가 존재하면 덮어쓰지 않고 개선 사항을 제안한다. /init으로 뼈대를 잡고, 거기서부터 다듬어 나가는 게 효율적이다.

② 직접 작성 및 업데이트

프로젝트 루트에 CLAUDE.md 파일을 만들고 마크다운으로 작성하면 된다. 가장 확실하고 통제력 있는 방법이다. 팀의 코딩 표준, 아키텍처 결정, 빌드/테스트 명령어 등 Claude가 알아야 할 것들을 적는다.

③ 대화 중 Claude에게 요청

작업하다가 규칙을 발견하면 그 자리에서 바로 반영할 수 있다. "이 규칙을 CLAUDE.md에 추가해줘"라고 말하면 Claude가 직접 파일을 수정한다.

주의할 점: 단순히 "이거 기억해줘"라고만 하면 CLAUDE.md가 아니라 자동 메모리(MEMORY.md)에 저장된다. CLAUDE.md에 넣고 싶으면 명시적으로 "CLAUDE.md에 추가해줘"라고 말해야 한다.

---

3. CLAUDE.md의 종류 — 범위별 3+1 구조

CLAUDE.md는 놓는 위치에 따라 적용 범위가 달라진다. 넓은 범위에서 좁은 범위 순으로 정리하면 이렇다.

① 사용자 글로벌 — ~/.claude/CLAUDE.md

내 모든 프로젝트에 걸쳐 적용되는 개인 설정이다. 어떤 프로젝트를 열든 항상 로드된다.

개인 코드 스타일, 선호하는 도구 설정, 응답 형식 선호도 등 프로젝트와 무관하게 항상 적용하고 싶은 것들을 담는다. 예를 들어 "응답은 항상 한국어로", "커밋 메시지는 영어로" 같은 것.

② 프로젝트 — ./CLAUDE.md

가장 핵심이 되는 레벨이다. 프로젝트 루트에 위치하며, git에 커밋해서 팀과 공유한다.

프로젝트 아키텍처, 코딩 표준, 빌드/테스트 명령어, 명명 규칙, 워크플로우 등을 담는다. 팀원 모두가 같은 CLAUDE.md를 공유하게 되므로 개인 선호도보다는 프로젝트 수준의 표준에 집중해야 한다.

③ 하위 디렉토리 — my-project/프로젝트 하위폴더/CLAUDE.md

프로젝트 안에서도 특정 기능이나 모듈에만 적용되는 지침을 둘 수 있다. 해당 디렉토리 안에 CLAUDE.md를 만들면 된다.

예를 들어 src/api/CLAUDE.md에 API 관련 규칙을, src/frontend/CLAUDE.md에 프론트엔드 규칙을 따로 둘 수 있다. 모노레포에서 팀별로 다른 규칙이 필요할 때 특히 유용하다.

+α 로컬 지침 — ./CLAUDE.local.md

git에 체크인되지 않는 개인 프로젝트별 설정이다. 자동으로 .gitignore에 추가된다.

로컬 샌드박스 URL, 테스트 데이터, 개인 디버깅 설정 등 나만 필요한 것들을 담는다. 팀 공유가 필요 없는 개인 설정을 프로젝트 CLAUDE.md와 분리할 수 있다.

---

4. 로드 규칙 — Context에 어떻게 포함되나?

기본 원칙

Claude Code는 세션 시작 시 현재 작업 디렉토리에서 위로 올라가며 발견되는 모든 CLAUDE.md를 수집한다. 아래 방향은 즉시 로드하지 않는다.

경우의 수별 정리

Case 1: 프로젝트 루트에서 실행 (my-project/)

✅ ~/.claude/CLAUDE.md          ← 사용자 글로벌 (항상 로드)
✅ my-project/CLAUDE.md         ← 프로젝트 지침 (현재 디렉토리)
✅ my-project/CLAUDE.local.md   ← 로컬 지침 (있다면)
❌ my-project/src/CLAUDE.md     ← 하위 디렉토리 → 시작 시 로드 안 됨
❌ my-project/src/api/CLAUDE.md ← 더 깊은 하위 → 시작 시 로드 안 됨

하위 디렉토리의 CLAUDE.md는 Claude가 해당 폴더의 파일을 실제로 읽거나 수정할 때 필요 시 로드된다. 즉, src/api/ 파일을 다루는 순간 src/api/CLAUDE.md가 컨텍스트에 추가된다.

 

 

Case 2: 하위 디렉토리에서 실행 (my-project/src/api/)

✅ ~/.claude/CLAUDE.md          ← 사용자 글로벌 (항상 로드)
✅ my-project/CLAUDE.md         ← 상위 디렉토리 → 올라가며 발견, 로드됨
✅ my-project/CLAUDE.local.md   ← 상위의 로컬 지침도 로드됨
✅ my-project/src/CLAUDE.md     ← 상위 디렉토리 → 올라가며 발견, 로드됨
✅ my-project/src/api/CLAUDE.md ← 현재 디렉토리 → 로드됨

이 경우 위로 올라가면서 만나는 모든 CLAUDE.md가 전부 로드된다. 프로젝트 루트의 규칙과 하위 디렉토리의 규칙이 동시에 적용되는 것이다.

 

 

Case 3: 프로젝트 루트에서 실행했지만, 작업 중 하위 파일을 다루는 경우

시작 시:
✅ ~/.claude/CLAUDE.md
✅ my-project/CLAUDE.md

작업 중 Claude가 src/api/handler.ts를 읽는 순간:
✅ my-project/src/api/CLAUDE.md ← 이 시점에 추가 로드됨

이게 핵심이다. 하위 디렉토리 CLAUDE.md는 지연 로드(lazy load) 방식으로 작동한다. 시작할 때 전부 읽지 않고, 해당 디렉토리 파일을 다루는 시점에 로드된다. 불필요한 컨텍스트 소비를 줄이기 위한 설계다.

 

우선순위

더 구체적인 위치(하위 디렉토리)의 지침이 더 광범위한 위치(상위 디렉토리)보다 우선한다. 다만 "덮어쓰기"가 아니라 "합산"이다. 상위 규칙도 여전히 적용되고, 하위 규칙이 추가로 적용된다.

---

5. 확장 기능 — rules 분리와 import

① .claude/rules/로 규칙 분리

프로젝트가 커지면 하나의 CLAUDE.md에 모든 규칙을 담기 어렵다. .claude/rules/ 디렉토리를 사용하면 주제별로 규칙 파일을 분리할 수 있다.

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    ├── security.md
    └── frontend/
        └── react-conventions.md

모든 .md 파일이 재귀적으로 발견되므로 하위 디렉토리로 추가 구성도 가능하다.

가장 강력한 기능은 경로별 조건부 적용이다. YAML frontmatter에 paths를 지정하면 특정 파일 패턴과 일치할 때만 해당 규칙이 로드된다.

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
---

# API 개발 규칙
- 모든 엔드포인트는 입력 검증 포함
- 표준 오류 응답 형식 사용

이 규칙은 src/api/ 아래 TypeScript 파일을 다룰 때만 컨텍스트에 들어간다. paths가 없는 규칙은 무조건 로드된다.

② @import 구문으로 외부 파일 참조

CLAUDE.md 안에서 다른 파일을 가져올 수 있다.

프로젝트 개요는 @README 참조
npm 명령은 @package.json 참조
git 워크플로우는 @docs/git-instructions.md 참조

상대 경로는 가져오기를 포함하는 파일 기준으로 해석된다. 최대 5홉 깊이까지 재귀적 가져오기를 지원한다.

---

 

6. 작성 원칙

①200줄 이하로 유지

CLAUDE.md는 매 세션 시작 시 컨텍스트 윈도우에 로드된다. 길수록 토큰을 많이 소비하고, 준수율도 떨어진다. 넘어가면 .claude/rules/로 분리하거나 @import를 활용한다.

②구체적으로 작성

검증할 수 있을 정도로 구체적인 지침이 잘 따라진다.

• "코드를 제대로 포맷해줘" ❌
• "2칸 들여쓰기 사용" ✅
• "변경 사항을 테스트해줘" ❌
• "커밋하기 전에 npm test 실행" ✅

③충돌 방지

두 규칙이 모순되면 Claude가 하나를 임의로 선택한다. CLAUDE.md, rules 파일, 하위 디렉토리 CLAUDE.md를 정기적으로 검토해서 오래되거나 충돌하는 지침을 제거해야 한다.

④/compact에도 살아남는다

/compact 후에도 CLAUDE.md는 사라지지 않는다. Claude가 디스크에서 다시 읽어서 새로 주입하기 때문이다. 반면 대화 중에만 언급한 규칙은 압축 시 사라질 수 있다. 세션 간에 지속되어야 하는 건 반드시 CLAUDE.md에 적어야 한다.