Claude Code를 며칠 쓰다 보면 같은 설명을 또 하고 있는 자신을 발견합니다. “이건 동네 빵집 예약 사이트야”, “새 프로그램은 함부로 설치하지 마”, “확인할 땐 이 명령으로 켜 봐”. CLAUDE.md는 이런 말을 한 번만 적어 두는 파일입니다.
공식 문서의 정의가 딱 그렇습니다.
“Treat CLAUDE.md as the place you write down what you’d otherwise re-explain.” (안 적어 두면 또 설명하게 될 내용을 적는 곳이라고 생각하세요.)
Claude Code는 세션(Claude Code를 켜서 끌 때까지의 대화 한 묶음)을 시작할 때마다 이 파일을 알아서 읽습니다. 결론은 간단합니다. 프로젝트 폴더 맨 위에 CLAUDE.md 파일을 하나 만들어 세 줄로 시작하고 Claude가 같은 실수를 두 번 하면 한 줄씩 더하세요.
2026년 9월 29일 기준, Claude Code v2.1.284와 공식 memory 문서로 확인했습니다.
.md는 마크다운(#나-같은 기호로 제목과 목록을 표시하는 글 형식) 파일이라는 뜻입니다. 메모장으로도 열리는 평범한 글 파일입니다.
CLAUDE.md는 ’AI에게 주는 헌법’입니다
비개발자에게 잘 통하는 설명 하나는 헌법 비유입니다. 한 비개발자 기획자는 AI 앱을 만들면서 AI가 모든 작업 전에 읽도록 가이드 문서.md를 작성했고 그 단계를 “AI에게 줄 ‘헌법’ 문서 만들기”라고 불렀습니다. 이 비유가 잘 맞는 이유는 헌법과 CLAUDE.md가 세 가지 성질을 똑같이 갖기 때문입니다.
하나, 매번 낭독하지 않아도 적용됩니다. 이 블로그 저장소의 CLAUDE.md는 9줄짜리입니다.
# dev.log
Astro static markdown blog (light single theme). Posts live in `src/content/posts/*.md`; see README.md for authoring and deploy.
## Subagent Model Routing
- **Development** (feature work, bug fixes, refactors) → dispatch subagents on **`sonnet`**.
- **Review** (code review, verification, SHIP/NO-SHIP verdicts) → dispatch subagents on **`opus`**.
- A sonnet dev agent never self-approves its own diff; commit only after an opus reviewer returns **SHIP**.마지막 줄은 “검토 담당 Claude가 통과(SHIP)를 주기 전에는 저장(커밋)하지 말라”는 규칙입니다. 2026년 9월 28일 이 시리즈의 요금제 편을 발행 준비할 때 저는 이 규칙을 한 번도 입에 올리지 않았습니다. 그런데도 Claude는 검토를 맡겼고 첫 판정이 불통과(NO-SHIP)로 나오자 커밋을 멈췄다가 고친 뒤 통과를 받고서야 커밋했습니다. 같은 규칙이 모든 프로젝트에 적용되는 사용자 지침(~/.claude/CLAUDE.md)에도 들어 있어 두 파일이 함께 작용했습니다. 헌법을 매일 아침 낭독하지 않아도 효력이 있는 것과 같습니다.
둘, 사건마다 해석이 필요합니다. “인간의 존엄”처럼 넓게 쓴 조항은 구체적인 사건 앞에서 해석이 갈립니다. CLAUDE.md도 “코드를 깔끔하게”처럼 쓰면 무엇이 깔끔한지는 Claude가 매번 짐작합니다. 공식 문서는 규칙을 “concrete enough to verify”(지켰는지 확인할 수 있을 만큼 구체적으로) 쓰라고 하고 두 규칙이 서로 부딪히면 “Claude may pick one arbitrarily”(Claude가 둘 중 하나를 임의로 고를 수 있다)고 경고합니다. 구체적으로 쓰는 요령과 예시는 CLAUDE.md 템플릿 글에 정리해 뒀습니다.
셋, 길어질수록 지켜지지 않습니다. 공식 권장 분량은 “target under 200 lines per CLAUDE.md file”(파일 하나당 200줄 미만)입니다. 이유도 적혀 있습니다. “Longer files consume more context and reduce adherence.” 길수록 Claude의 기억 공간을 더 차지하고 지키는 비율은 떨어진다는 뜻입니다.
제 컴퓨터의 사용자 지침(~/.claude/CLAUDE.md)을 줄인 기록도 하나 있습니다. 2026년 9월 28일에 134줄에서 25줄로 바뀌었습니다. 134줄도 공식 권장치 200줄 안이었습니다. 3계층 구조를 글자로 그린 도식이 든 57줄짜리 섹션과 스킬·에이전트 목록 표가 빠졌고, 소통·작업 흐름·서브에이전트·계층 원칙·UI 기본값 다섯 섹션이 남았습니다.
비유가 깨지는 곳: CLAUDE.md에는 강제력이 없습니다
헌법은 어기면 위헌 판결이 나옵니다. CLAUDE.md는 그렇지 않습니다. 공식 문서의 표현입니다.
“Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.” (Claude는 이 파일들을 강제 설정이 아니라 참고 맥락으로 다룹니다. Claude의 판단과 상관없이 어떤 행동을 막으려면 PreToolUse 훅을 쓰세요.)
그러니 CLAUDE.md는 명령서가 아니라 참고 자료입니다. “결제 폴더는 절대 수정 금지”처럼 어기면 사고가 나는 규칙은 CLAUDE.md에 적어 두는 것만으로 안전하지 않습니다. 그런 규칙은 훅(Hook, 도구 실행 직전·직후처럼 정해진 시점에 자동으로 도는 명령)으로 막아야 하고 훅은 이 시리즈 뒤쪽에서 따로 다룹니다. CLAUDE.md가 시스템 프롬프트가 아니라 사용자 메시지로 전달된다는 기술적인 배경은 템플릿 글에 있습니다.
Claude의 ‘진짜 헌법’, 오토 메모리와 무엇이 다른가
“Claude 헌법”으로 검색하면 CLAUDE.md가 아닌 문서가 먼저 나올 수 있습니다. Anthropic이 2026년 1월 공개한 Claude’s Constitution입니다. 이 문서는 “plays a crucial role in our training process”, 즉 모델을 훈련하는 단계에서 Claude의 가치관과 행동을 만드는 데 쓰입니다. 우리가 고칠 수 있는 파일이 아닙니다.
비슷해 보이는 것들을 한 표에 놓으면 이렇습니다.
| 누가 쓰나 | 언제 적용되나 | 강제력 | |
|---|---|---|---|
| Claude’s Constitution | Anthropic | 모델 훈련 단계 | 모델의 가치관·행동에 반영 |
| CLAUDE.md | 나(또는 팀) | 세션을 시작할 때마다 | 없음 (참고 맥락) |
| 채팅창에 친 지시 | 나 | 그 대화 안에서만 | 없음 |
| 오토 메모리 | Claude | 세션을 시작할 때마다 (처음 200줄 또는 25KB) | 없음 |
| 훅 | 나 | 정해진 시점 (예: 행동 직전) | 있음 (행동을 막을 수 있음) |
채팅창에 친 지시와 CLAUDE.md의 차이는 생각보다 큽니다. 공식 문서에 따르면 대화가 길어져 /compact(대화 요약)가 일어나도 프로젝트 폴더 맨 위의 CLAUDE.md는 디스크에서 다시 읽혀 들어갑니다. 반대로 요약 뒤에 지시가 사라졌다면 대개 “given only in conversation”, 대화에서만 했던 말이었기 때문입니다. 하위 폴더에 둔 CLAUDE.md가 아직 다시 읽히지 않은 경우도 있습니다.
오토 메모리는 Claude가 스스로 적는 메모장입니다. 여기서 헷갈리기 쉬운 점이 하나 있습니다. Claude에게 “기억해”라고 말하면 CLAUDE.md가 아니라 오토 메모리에 저장됩니다. CLAUDE.md에 넣고 싶으면 “이거 CLAUDE.md에 추가해 줘”라고 파일 이름을 짚어서 말해야 합니다. 오토 메모리는 따로 한 편을 할애해 다룹니다.
언제 적나: 공식 기준은 ’두 번째’입니다
공식 문서는 CLAUDE.md에 한 줄을 더할 때를 네 가지로 꼽습니다.
- Claude가 같은 실수를 두 번째 할 때
- 결과물을 검토하다가 “이건 Claude가 이 프로젝트에 대해 알았어야지” 싶은 게 나왔을 때
- 지난 세션에 했던 정정을 이번 세션 채팅창에 또 치고 있을 때
- 새로 합류한 사람에게도 똑같이 설명해야 할 맥락일 때
이 블로그의 템플릿 글은 “같은 지시를 세 번째 붙여넣고 있다면” 파일로 옮기라고 썼습니다. 여기서 바로잡습니다. 공식 기준은 그보다 한 번 빠른 두 번째입니다. 같은 실수를 한 번 더 참을 이유가 없습니다.
반대로 적지 말아야 할 것도 있습니다. 공식 문서는 CLAUDE.md를 “매 세션 알고 있어야 할 사실”로 채우라고 합니다. 실행 명령, 약속, 폴더 구조, “항상 X 하라” 같은 규칙입니다. 여러 단계로 된 절차나 특정 폴더에만 해당하는 내용은 스킬이나 규칙 파일로 옮기라고 권합니다. 무엇을 넣고 뺄지는 다음 편들에서 자세히 나눕니다.
3분이면 되는 첫 CLAUDE.md: 세 줄
위치는 프로젝트 폴더 맨 위(루트)입니다. CLAUDE.md를 둘 수 있는 곳은 몇 군데 더 있고 읽히는 순서도 정해져 있는데, 그건 다음 편에서 다룹니다. 폴더 구조 전체가 궁금하면 .claude 디렉터리 지도를 보세요.
처음에는 세 줄이면 됩니다. 이 프로젝트가 무엇인지 한 줄, 하지 말아야 할 것 한 줄, 확인할 때 쓰는 명령 한 줄입니다.
# 동네 빵집 예약 사이트
- 손님이 빵을 미리 예약하는 웹사이트입니다. 사장님 혼자 관리하므로 화면은 단순하게 유지합니다.
- 새 프로그램(라이브러리)을 설치하기 전에는 무엇을 왜 설치하는지 먼저 물어보세요.
- 결과는 `npm run dev`로 실행해서 확인합니다.만드는 방법은 세 가지입니다. 편한 쪽을 고르세요.
- Claude에게 부탁하기: 채팅창에 “이 폴더에 CLAUDE.md 파일 만들고 아래 세 줄 적어 줘”라고 치고 세 줄을 붙여 넣습니다.
/memory로 만들기:/memory를 치면 CLAUDE.md 위치 목록이 나옵니다. 아직 없는 파일을 고르면 새로 만들어서 편집기로 열어 줍니다./init으로 자동 생성하기: Claude가 폴더를 훑어보고 실행 명령과 약속을 찾아 초안을 써 줍니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 고칠 점을 제안합니다. 빈 폴더에서는 찾을 게 없으니 코드가 좀 쌓인 뒤에 쓰는 편이 낫습니다.
여기서 막힙니다: 적었는데 안 읽히는 것 같을 때
먼저 /context를 치세요. 화면에 나오는 Memory files 목록에 CLAUDE.md가 보이면 읽힌 것입니다. 공식 문서는 여기에 없으면 “Claude can’t see it”, 즉 Claude가 볼 수 없다고 적습니다.
목록에 없다면 대부분 위치 문제입니다. 프로젝트 CLAUDE.md는 Claude Code를 켠 폴더(작업 디렉터리)와 그 위쪽 폴더에 있는 것만 시작할 때 읽힙니다. 하위 폴더에 넣어 둔 CLAUDE.md는 Claude가 그 폴더의 파일을 읽을 때 뒤늦게 읽힙니다. 켜기 전에 cd로 프로젝트 폴더에 들어갔는지부터 확인하세요. 방법은 첫 세션 10분 글에 있습니다.
목록에는 있는데 지켜지지 않는다면 앞에서 말한 두 번째와 세 번째 성질을 의심하세요. 규칙이 모호하거나, 서로 부딪히거나, 파일이 너무 긴 경우입니다. 강제력이 없다는 점도 다시 떠올리세요.
처음부터 잘 쓸 필요는 없습니다
완벽한 CLAUDE.md를 한 번에 쓰려고 하면 오히려 길어집니다. 그러면 세 번째 성질에 걸립니다. 세 줄로 시작해서 Claude가 같은 실수를 두 번 할 때마다 한 줄씩 붙이는 게 정석입니다.
이 블로그의 CLAUDE.md도 2026년 8월 20일 첫 커밋 이후 한 번도 고치지 않았습니다. 다만 그 사이 모든 교훈이 CLAUDE.md로 간 것은 아닙니다. 발행 절차처럼 여러 단계짜리 규칙은 스킬 파일로 갔고 Claude가 작업하며 배운 주의사항은 오토 메모리에 쌓였습니다. CLAUDE.md는 모든 걸 담는 곳이 아니라 매 세션 꼭 알아야 할 것만 담는 곳입니다. 이렇게 규칙과 장치로 AI의 작업 환경을 짜는 일을 넓게는 하네스 엔지니어링이라고 부릅니다.