CLAUDE.md 제대로 쓰는 법 — Claude Code 기억·규칙·커스텀 명령 완전 가이드 (2026)
Claude Code를 처음 켰을 때와 3개월 쓴 뒤의 결과물 차이는 대부분 모델이 아니라 이 파일 하나에서 갈립니다. CLAUDE.md를 어디에 두고, 무엇을 적고, 무엇을 절대 넣지 말아야 하는지 실전 기준으로 정리했습니다.
같은 프롬프트, 같은 모델인데 어떤 사람의 Claude Code는 프로젝트 규칙을 알아서 지키고 어떤 사람은 매번 "테스트는 pytest로 돌려"를 반복합니다. 이 차이는 재능이 아니라 세션이 시작될 때 Claude가 무엇을 읽고 들어오느냐에서 갈립니다. 그 정체가 바로 CLAUDE.md입니다.
CLAUDE.md가 뭐길래 — 전체 워크플로 레버리지 1위
CLAUDE.md는 Claude Code가 매 세션 시작 시 시스템 프롬프트에 자동으로 주입하는 마크다운 파일입니다. 대화를 시작하는 순간 이미 읽혀 있죠. 그래서 여기 적은 한 줄은 "이번 답변"이 아니라 앞으로 나올 모든 답변에 곱해집니다.
레버리지가 가장 큰 동시에 위험도 큽니다. "npm 말고 pnpm을 쓴다"를 한 줄 적으면 다시는 잘못된 설치 명령을 안 봅니다. 반대로 오래돼 틀린 규칙 한 줄은 모든 산출물을 조용히 오염시킵니다. 그래서 CLAUDE.md는 "Claude에게 보내는 편지"가 아니라 "Claude가 항상 지켜야 하는 계약서"입니다. 길게 설명할 곳이 아니라, 짧고 단호하게 규칙을 박는 곳.
6계층 메모리 지도 — 어디에 무엇을 넣나
Claude Code의 메모리는 파일 하나가 아니라 여러 계층으로 겹쳐 로드됩니다. 넓은 범위(조직·개인)가 먼저 깔리고, 좁은 범위(프로젝트·디렉터리)가 그 위에 얹혀 더 구체적인 규칙이 우선합니다. 전체 지도는 이렇습니다.
| 계층 | 위치 | 용도 |
|---|---|---|
| 관리 정책(Enterprise) | /etc/claude-code/CLAUDE.md | 회사 IT가 배포하는 조직 공통 규칙. 1인 개발자는 신경 쓸 필요 없음 |
| 사용자(User) | ~/.claude/CLAUDE.md | 모든 프로젝트에 적용되는 내 개인 취향(보안 습관·기본 스타일) |
| 프로젝트(Project) | ./CLAUDE.md | 팀과 git으로 공유하는 저장소 규칙. 가장 많이 쓰는 계층 |
| 디렉터리 | 하위 폴더의 CLAUDE.md | 그 폴더에서 작업할 때만 추가로 로드되는 모듈별 규칙 |
| 로컬(개인) | CLAUDE.local.md | gitignore되는 나만의 임시 오버라이드 |
| 오토 메모리 | ~/.claude/projects/.../memory/ | Claude가 스스로 적어두는 노트(사람이 쓰는 CLAUDE.md와 별개) |
실전에서 개인 개발자가 매일 만지는 건 사실 두 개뿐입니다. 프로젝트 ./CLAUDE.md(이 저장소는 이렇게 다뤄라)와 사용자 ~/.claude/CLAUDE.md(나는 원래 이렇게 일한다). 나머지는 "이런 것도 있다"만 알아두고, 필요해질 때 꺼내 쓰면 됩니다.
잘 쓰는 5원칙과 복붙 템플릿
Anthropic 공식 가이드가 제시하는 판단 기준은 의외로 단순합니다. "Claude가 코드를 읽어서 알 수 있는 건 넣지 말고, 알 수 없는 것만 넣어라." 표준 문법이나 자명한 관례는 뺍니다. 대신 추측 불가능한 빌드 명령, 기본과 다른 코드 스타일, 선호 테스트 러너, 환경 변수 같은 비자명한 규칙만 담습니다. 이 기준을 5가지 실천 원칙으로 풀면:
- 짧게 유지한다. 매 세션 로드되므로 소설을 쓰면 컨텍스트를 낭비합니다. 200줄 안쪽을 권장.
- 명령형으로 쓴다. "가급적 목을 피하려 합니다"가 아니라 "테스트에 인라인 목 금지 —
src/test/factories/를 써라". - 문단보다 불릿. Claude는 리스트를 더 정확히 파싱합니다. 설명 문단을 짧은 항목으로 쪼개세요.
- 금지 목록을 명시한다. "하지 마라"가 "해라"보다 사고를 더 많이 막습니다.
- 문서는 링크로 대체한다. API 레퍼런스를 통째로 붙여넣지 말고
@README.md처럼 참조만 겁니다.
바로 복사해 시작할 수 있는 최소 골격입니다. 15줄이면 웬만한 프로젝트의 80%를 커버합니다.
개발 프로젝트용 ./CLAUDE.md
# 프로젝트: 결제 API 서버
## 명령
- 설치: pnpm install (npm 금지)
- 테스트: pnpm test (단일: pnpm test -- path/to/file)
- 개발서버: pnpm dev
## 코드 규칙
- TypeScript strict. any 금지 — unknown 후 좁혀라
- 날짜는 항상 UTC 저장, 표시 단에서만 변환
## 하지 마라
- /generated/ 안의 파일 수정 금지
- .env 새로 만들지 마라 — 값은 Vault에서 온다
- 의존성 추가 전 반드시 물어봐라
## 참조
자세한 아키텍처는 @docs/architecture.md 참고개발자가 아니어도 똑같이 강력합니다. 콘텐츠·마케팅 작업이라면 "코드 규칙" 자리에 톤·금칙어·포맷을 넣으면 됩니다.
콘텐츠 작업용 ~/.claude/CLAUDE.md
# 나의 작업 기본값
## 글쓰기 톤
- 한국어. 존댓말. 과장·낚시 제목 금지
- 문장은 짧게. 한 문단 3~4문장
## 금칙 표현
- "~의 시대가 열렸습니다" 류 상투어 금지
- 근거 없는 둥근 수치("약 30%") 금지 — 출처 있는 값만92% → 96%
SFEIR Institute 실측에 따르면, 규칙을 하나의 CLAUDE.md(200줄)에 몰아넣었을 때 규칙 적용률은 92%, 이를 .claude/rules/로 모듈화하면 96%로 올라가고 컨텍스트 토큰은 약 40% 줄었습니다. 길게 쓴다고 더 잘 지켜지는 게 아니라는 뜻입니다.
한 단계 위: 모듈러 규칙과 실수에서 배우는 커스텀 명령
여기서 대부분의 초보자가 반대로 갑니다. 규칙이 늘어나면 CLAUDE.md에 계속 덧붙여 파일을 비대하게 만들죠. 그런데 앞의 수치가 말하듯 비대한 파일은 적용률을 오히려 떨어뜨립니다. 해법은 쪼개는 것.
.claude/rules/ 폴더에 주제별 마크다운을 두면 그 파일은 관련 있는 상황에서만 로드됩니다. 테스트 규칙은 *.test.ts를 만질 때만 켜지도록 글롭 패턴을 걸 수 있어, 평소엔 시스템 프롬프트에서 노이즈가 빠집니다.
또 하나 강력한 패턴은 "실수를 규칙으로, 규칙을 명령으로"입니다. 디버깅으로 한참 헤맸다면 그 교훈을 CLAUDE.md에 한 줄 남기세요(발견 날짜와 함께). 다음에 같은 코드를 만나면 Claude가 기억합니다 — 팀 전체가 같은 버그를 두 번 겪지 않죠. 반복 지시라면 아예 .claude/commands/에 저장해 커스텀 슬래시 명령으로 만들 수 있습니다.
기억해둘 관리 명령은 세 개뿐입니다.
| 명령 | 언제 쓰나 |
|---|---|
/init | 기존 코드베이스를 분석해 CLAUDE.md 초안을 자동 생성. 처음 한 번 |
/memory | 세션 도중 에디터로 메모리 파일을 열어 크게 손볼 때 |
# 규칙 한 줄 | 대화 중 #으로 시작하면 그 규칙을 즉시 메모리에 저장 |
순서는 명확합니다. /init로 뼈대를 만들고, Claude가 스스로 알 수 없는 것만 내가 채워 넣고, 이후엔 #로 매일 조금씩 다듬는 겁니다. 공식 문서는 Claude Code 메모리 문서에서 확인할 수 있습니다.
흔한 실수 3가지
실수 1 — /init만 돌리고 방치. /init이 만든 초안은 시작점일 뿐입니다. Claude가 코드에서 읽어낼 수 있는 자명한 내용이 대부분이라, 정작 중요한 "추측 불가능한 규칙"은 내가 손으로 넣어야 진짜 효과가 납니다.
실수 2 — 파일이 계속 길어짐. 규칙을 지울 줄 모르면 CLAUDE.md는 수백 줄로 붑니다. 매 세션 로드되므로 이건 곧 비용이자 노이즈입니다. 분기에 한 번은 가지치기(pruning)하고, 늘어나면 .claude/rules/로 분리하세요.
실수 3 — 문서를 통째로 복붙. 라이브러리 API 문서·긴 튜토리얼을 CLAUDE.md에 붙여넣는 건 최악의 컨텍스트 낭비입니다. 자주 바뀌는 정보는 특히 금물. @경로 임포트로 참조하거나, 최신 문서가 필요하면 Context7 같은 MCP로 그때그때 불러오는 편이 훨씬 정확합니다.
정리하면 CLAUDE.md 관리의 본질은 "무엇을 더 적을까"가 아니라 "무엇을 안 적을까"입니다. Claude가 이미 아는 건 빼고, 모르는 것만 짧고 단호하게. 그 한 줄이 앞으로의 모든 세션에 곱해진다는 감각만 있으면, 당신의 Claude Code는 매주 조금씩 더 똑똑해집니다. 오늘 당장 프로젝트 루트에서 /init부터 눌러보세요 — 지금 여러분의 CLAUDE.md에서 가장 먼저 지워야 할 한 줄은 무엇인가요?