CLAUDE.md — Claude Code가 세션을 시작할 때마다 읽어 들이는, 사람이 직접 쓰는 프로젝트 지침 파일입니다. 이 글은 공식 memory 문서에 실제로 나오는 권장사항을 거꾸로 뒤집어, usingclaude.com이 흔히 보는 CLAUDE.md 실수 6가지를 나쁜 예와 좋은 예로 나란히 비교합니다. CLAUDE.md 파일이 이미 있는 프로젝트라면 5분 안에 훑어보고 바로 고칠 곳을 찾을 수 있습니다.
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
CLAUDE.md와 자동 메모리, 무엇이 다른가요?
CLAUDE.md는 사람이 직접 써 두는 지침 파일이고, 자동 메모리(auto memory)는 Claude가 사용자의 교정과 취향을 바탕으로 스스로 기록하는 학습 노트입니다. 공식 문서는 "CLAUDE.md는 Claude의 행동을 이끌고 싶을 때, 자동 메모리는 수고를 들이지 않고 Claude가 사용자의 교정으로부터 배우게 하고 싶을 때" 쓰라고 구분합니다. 위 도식처럼 CLAUDE.md는 사람이 전부 작성해 매 세션 통째로 로드되고, 자동 메모리는 Claude가 저장소 단위로 쌓아 두되 세션당 앞부분(최대 200줄 또는 25KB)까지만 불러옵니다. 이 차이를 모르고 두 시스템의 역할을 뒤섞는 것 자체가 아래 안티패턴 6의 원인이 됩니다.
용어 빠른 풀이
- CLAUDE.md — 프로젝트나 개인 작업 방식을 위해 사람이 직접 쓰는 마크다운 지침 파일입니다.
- 자동 메모리(auto memory) — Claude가 교정·취향을 바탕으로 스스로 기록해 두는 학습 노트입니다.
- 스킬(skill) — 여러 단계로 된 절차를 별도 파일로 분리해 두는 기능입니다. 공식 문서는 다단계 절차나 특정 부분에만 해당하는 내용은 CLAUDE.md 대신 스킬이나 경로 스코프 규칙으로 옮기라고 안내합니다.
- 경로 스코프 규칙(path-scoped rule) —
.claude/rules/에 두어 특정 경로·파일 유형에만 적용되도록 범위를 좁힌 지침입니다. - 훅(hook), 그중 PreToolUse 훅 — 특정 상황에 자동으로 실행되는 규칙입니다. 공식 문서에 따르면 Claude는 CLAUDE.md를 "강제 설정이 아니라 맥락"으로 다루므로, Claude의 판단과 무관하게 어떤 동작을 반드시 막고 싶다면 PreToolUse 훅을 써야 합니다.
- CLAUDE.local.md — 이 프로젝트에서 나만 쓰는 개인 취향을 적는 파일로,
.gitignore에 넣어 커밋되지 않게 합니다.
| 안티패턴 | 왜 문제인가요 | 고치는 법 |
|---|---|---|
| 1. 너무 길고 잡다하게 쓰기 | 구체적·간결할수록 잘 따르는데 반대로 감 | 핵심 규칙만 짧게 남기기 |
| 2. 한 부분에만 쓰는 절차를 최상위에 넣기 | 다단계 절차는 CLAUDE.md 몫이 아님 | 스킬·경로 스코프 규칙으로 이동 |
| 3. CLAUDE.md를 강제 차단으로 착각 | Claude는 이를 맥락으로만 다룸 | 확실한 차단은 PreToolUse 훅으로 |
| 4. 개인 정보를 팀 공유 파일에 커밋 | ./CLAUDE.md는 소스 관리로 팀과 공유됨 | CLAUDE.local.md로 옮기고 .gitignore |
| 5. 반복 교정을 기록하지 않음 | 같은 설명을 세션마다 다시 해야 함 | 두 번째 반복되면 바로 기록 |
| 6. CLAUDE.md와 자동 메모리 역할 혼동 | Claude가 알아서 쌓을 내용을 손으로 관리 | /memory로 확인, 역할 분리 |
안티패턴 1. CLAUDE.md를 너무 길고 잡다하게 채우기
구체적이고 간결한 지침일수록 Claude가 더 일관되게 따르므로, 이것저것 다 밀어 넣은 CLAUDE.md는 오히려 역효과를 냅니다. 공식 문서는 "지침이 구체적이고 간결할수록 Claude가 더 일관되게 따른다"고 명시하며, CLAUDE.md가 지나치게 커졌을 때 생기는 문제를 별도 트러블슈팅 항목으로 다룰 만큼 흔한 실수로 취급합니다.
❌ 나쁜 예
- 이 프로젝트는 예전부터 이런저런 이유로 시작됐고...
- 코드는 되도록 깔끔하고 예쁘게 써주세요
- 커밋 전에 이것저것 확인하면 좋습니다
- 가끔 CI가 이상하게 실패하는데 그냥 재시도하면 됩니다
✅ 좋은 예
- 빌드: npm run build / 테스트: npm run test
- 커밋 전 lint 통과 필수
- API 응답은 항상 camelCase 사용나쁜 예는 "되도록", "이것저것", "가끔" 같은 모호한 표현으로 채워져 있어 Claude가 무엇을 지켜야 하는지 판단하기 어렵습니다. 좋은 예처럼 구체적인 명령어와 "항상 X 하라"는 형태의 규칙만 남기면 지침이 더 잘 지켜집니다.
안티패턴 2. 특정 부분에만 해당하는 절차를 최상위 CLAUDE.md에 넣기
여러 단계로 이뤄진 절차이거나 코드베이스의 한 부분에만 해당하는 내용이라면 CLAUDE.md가 아니라 스킬이나 경로 스코프 규칙으로 옮겨야 합니다. 공식 문서는 정확히 이 기준을 제시합니다. "항목이 다단계 절차이거나 코드베이스의 한 부분에만 해당한다면, 대신 스킬이나 경로 스코프 규칙으로 옮기라"는 것입니다.
❌ 나쁜 예 (최상위 CLAUDE.md)
- 결제 모듈 배포 절차:
1) 스테이징 배포
2) QA 승인 대기
3) 마이그레이션 스크립트 실행
4) 프로덕션 배포
5) 모니터링 대시보드 확인
...(계속)
✅ 좋은 예
- 결제 모듈 배포 절차 → skills/deploy-payment 참고
- (결제 모듈 배포 절차 전문은 별도 스킬 파일로 이동)배포 절차처럼 특정 상황에서만 필요한 여러 단계짜리 내용을 최상위에 그대로 두면, 이 절차와 무관한 작업을 할 때도 매번 전체가 로드되어 CLAUDE.md만 계속 길어집니다. 스킬이나 .claude/rules/의 경로 스코프 규칙으로 옮기면 필요할 때만 불러올 수 있습니다.
안티패턴 3. CLAUDE.md를 강제 차단 장치로 착각하기
CLAUDE.md에 "절대 하지 마세요"라고 적어도 이는 Claude에게 참고할 맥락일 뿐, 반드시 지켜지는 강제 설정이 아닙니다. 공식 문서는 "Claude는 이를 맥락으로 다루지, 강제 설정으로 다루지 않는다. Claude가 어떤 결정을 내리든 상관없이 동작을 막고 싶다면 대신 PreToolUse 훅을 사용하라"고 분명히 밝힙니다.
❌ 나쁜 예
- 프로덕션 DB에는 절대 연결하지 마세요
(→ CLAUDE.md에 적어 두기만 하고 "이제 안전하다"고 믿음)
✅ 좋은 예
- 프로덕션 DB에는 연결하지 않습니다 (CLAUDE.md, 맥락 안내용)
- + 위험한 명령 실행 자체를 막는 PreToolUse 훅 설정
(Claude의 판단과 무관하게 강제로 차단)CLAUDE.md의 문구는 Claude가 대부분의 경우 따르는 지침이지 100% 보장은 아닙니다. 절대 일어나서는 안 되는 동작이 있다면, 문구를 적는 것과 별개로 PreToolUse 훅으로 실제 차단 장치를 마련해야 합니다.
안티패턴 4. 개인 전용 정보를 팀 공유 CLAUDE.md에 커밋하기
나만 쓰는 샌드박스 주소나 테스트 데이터는 팀과 공유되는 프로젝트 CLAUDE.md가 아니라 CLAUDE.local.md에 적어야 합니다. 공식 문서의 위치 안내 표를 보면, 프로젝트 지침(./CLAUDE.md)은 "소스 관리를 통해 팀원과 공유"되는 반면, 로컬 지침(./CLAUDE.local.md)은 "개인적인 프로젝트별 취향"을 담고 ".gitignore에 추가"하도록 안내하며 예시로 "여러분의 샌드박스 URL, 선호하는 테스트 데이터"를 듭니다.
❌ 나쁜 예 (./CLAUDE.md, 팀과 공유·커밋됨)
- 제 로컬 테스트 DB는 localhost:5433입니다
- 제 개인 스테이징 서버: my-sandbox.example.com
✅ 좋은 예
./CLAUDE.md → 팀 전체가 쓰는 빌드·규칙만
./CLAUDE.local.md → 개인 샌드박스 주소, 테스트 데이터
(.gitignore에 추가)주의할 점은 프로젝트 CLAUDE.md는 소스 관리로 커밋되어 팀원 전체가 본다는 사실입니다. 나만 쓰는 URL이나 테스트 계정 정보를 실수로 여기 적으면 다른 팀원의 세션에도 그대로 로드됩니다.
안티패턴 5. 반복되는 교정을 기록하지 않고 매번 다시 설명하기
같은 실수나 같은 교정이 반복된다면 그 순간이 CLAUDE.md에 적어야 할 신호입니다. 공식 문서는 CLAUDE.md에 추가할 시점을 네 가지로 명시합니다. "Claude가 같은 실수를 두 번째로 저질렀을 때", "코드 리뷰에서 이 코드베이스에 대해 Claude가 알았어야 할 것이 발견됐을 때", "지난 세션에 입력했던 것과 같은 교정이나 설명을 채팅에 다시 입력할 때", "새 팀원이 생산성을 내려면 같은 맥락이 필요할 때"입니다.
❌ 나쁜 예
세션1: "커밋 메시지는 한국어로 써주세요"
세션2: "아, 커밋 메시지는 한국어로 부탁드려요"
세션3: "커밋 메시지 한국어로요!" (계속 반복)
✅ 좋은 예
같은 교정이 두 번째 나온 순간 CLAUDE.md에 한 줄 추가:
- 커밋 메시지는 한국어로 작성공식 문서는 "여러분이 어차피 다시 설명하게 될 내용을 적어 두는 곳"이 CLAUDE.md라고 표현합니다. 매 세션 같은 말을 반복하고 있다면, 그 문장을 그대로 CLAUDE.md에 옮기는 것만으로 이 안티패턴이 해결됩니다.
안티패턴 6. CLAUDE.md와 자동 메모리의 역할을 혼동하기
Claude가 알아서 배워 쌓아 둘 디버깅 통찰이나 사소한 취향까지 사람이 손으로 CLAUDE.md에 옮겨 적고 있다면, 두 시스템의 역할이 뒤섞인 것입니다. 공식 문서의 비교표에 따르면 CLAUDE.md의 용도는 "코딩 표준, 워크플로, 프로젝트 아키텍처"이고, 자동 메모리의 용도는 "빌드 명령, 디버깅 통찰, 취향"입니다. 후자는 Claude가 사용자의 교정으로부터 스스로 기록하도록 두는 편이 맞습니다.
❌ 나쁜 예
- (Claude가 이미 스스로 배운) 디버깅 팁, 사소한 취향을
사람이 매번 CLAUDE.md에 손으로 옮겨 적음
✅ 좋은 예
- CLAUDE.md에는 "항상 지켜야 할 규칙"만
- 디버깅 통찰·취향은 자동 메모리가 알아서 축적
- 무엇이 저장됐는지 궁금하면 /memory 명령으로 확인·수정공식 문서의 "자동 메모리 감사·수정" 섹션은 /memory 명령으로 저장된 내용을 확인하고 고칠 수 있다고 안내합니다. CLAUDE.md에 무엇을 손으로 적을지 고민될 때는, 먼저 /memory로 이미 자동 기록된 내용이 있는지 확인하는 습관을 들이면 중복 작업을 줄일 수 있습니다.
어디에 무엇을 적어야 하나요?
공유 범위에 따라 관리 정책 파일, 사용자 CLAUDE.md, 프로젝트 CLAUDE.md, CLAUDE.local.md 중 하나를 고르면 됩니다. 공식 문서는 이 네 위치를 "범위가 넓은 것부터 좁은 것 순"으로 나열하며, 이 순서대로 로드되어 프로젝트 지침이 사용자 지침 뒤에 맥락으로 쌓인다고 설명합니다.
또한 상위 디렉터리의 CLAUDE.md·CLAUDE.local.md는 실행 시 전체가 로드되지만, 하위 디렉터리에 둔 파일은 Claude가 그 디렉터리의 파일을 읽을 때 필요한 시점에만 불러옵니다. 큰 프로젝트라면 이 하위 디렉터리 로드 방식이나 .claude/rules/의 경로 스코프 규칙을 활용해 안티패턴 1·2에서 다룬 "너무 길고 잡다한 CLAUDE.md" 문제를 함께 줄일 수 있습니다.
자주 묻는 질문
Q. CLAUDE.md에 "이 명령은 절대 실행하지 마세요"라고 적으면 완전히 막을 수 있나요?
아니요, 완전히 막을 수는 없습니다. 공식 문서에 따르면 Claude는 CLAUDE.md를 맥락으로 다룰 뿐 강제 설정으로 다루지 않으므로, Claude의 판단과 무관하게 반드시 막고 싶은 동작이 있다면 PreToolUse 훅을 따로 설정해야 합니다.
Q. 자동 메모리에 무엇이 저장됐는지 어떻게 확인하나요?/memory 명령으로 확인하고 수정할 수 있습니다. 공식 문서는 자동 메모리 감사·수정 방법으로 이 명령을 안내합니다.
Q. CLAUDE.md 파일은 세션마다 항상 전부 다 읽히나요?
작업 디렉터리 상위에 있는 CLAUDE.md·CLAUDE.local.md는 실행 시 전체가 로드되지만, 하위 디렉터리의 파일은 Claude가 그 디렉터리 안의 파일을 읽을 때 필요할 때만 불러옵니다.
Q. 관리 정책, 사용자, 프로젝트, 로컬 CLAUDE.md를 동시에 쓰면 어떤 순서로 적용되나요?
범위가 넓은 것부터 좁은 것 순으로 로드됩니다. 공식 문서 표는 이 순서를 관리 정책 → 사용자 지침 → 프로젝트 지침 → 로컬 지침 순으로 나열하며, 그 결과 프로젝트 지침이 사용자 지침보다 뒤에 맥락으로 쌓인다고 설명합니다.
여섯 가지 안티패턴 모두 공통점이 있습니다. CLAUDE.md는 "구체적이고 간결한 지침"일 때 가장 잘 작동하며, 그 범위를 벗어나는 내용(다단계 절차, 강제 차단, 개인 정보, Claude가 알아서 배울 내용)은 각자 맞는 자리—스킬, 훅, CLAUDE.local.md, 자동 메모리—로 보내주는 것이 공식 문서가 말하는 정리 원칙입니다.