CLAUDE.md를 처음 만들 때 제일 흔한 실수는 빈 파일이 무서워서 아무거나 채우는 것입니다. 폴더 구조를 나열하고, 기술 스택을 적고, “코드는 깔끔하게”류의 다짐을 넣죠. 그 항목들은 전부 자리만 차지합니다 — 모델이 폴더를 열어보면 3초 만에 알 수 있는 것들이니까요.
지난 컨텍스트 전수 점검 글에서 스킬 49개와 CLAUDE.md 9개를 전수 점검하면서 이 기준을 실전으로 확인했습니다. 이번 글은 그 결과를 뒤집어서, 백지에서 CLAUDE.md를 어떻게 채우는지 순서대로 정리한 세팅 가이드입니다.
원칙은 한 문장이다
열어보면 알 수 있는 것은 쓰지 않는다. 겪어봐야 아는 것만 쓴다.
지난 점검에서 제일 큰 7.3KB짜리 CLAUDE.md가 만점을 받은 이유가 이거였습니다. 용량이 큰데도 내용이 전부 “Xcode GUI로 설정 만지지 마라(생성 파일이라 날아간다)” 같은 함정, “유료 계정 없으니 시뮬레이터 검증만” 같은 제약, “이 아키텍처는 재논의 금지” 같은 확정사항이었거든요. 코드를 아무리 읽어도 알 수 없는 것들입니다.
반대로 프로젝트 구조 나열은 지울수록 좋아집니다. Claude 5 세대 모델 기준으로 앤트로픽이 자기네 시스템 프롬프트를 80% 넘게 지우고도 성능 손실이 없었다는 게 원문 근거고요 — 모델이 스스로 찾을 수 있는 정보를 미리 적어주는 건 도움이 아니라 비용입니다.
어디에 두는 물건인가부터
CLAUDE.md는 위치에 따라 로드되는 범위가 다릅니다. 이걸 모르면 “글로벌에 다 몰아넣기”라는 두 번째 흔한 실수를 하게 됩니다.
- 글로벌은 모든 프로젝트에 따라붙는 세금입니다. “답변은 한국어로” 수준의 진짜 전역 규칙이 아니면 넣지 않습니다.
- 프로젝트 루트가 세팅의 중심입니다. 아래 내용 전부가 여기 이야기입니다.
- 하위폴더는 “이 폴더만 규칙이 다르다”가 실제로 있을 때만 만듭니다. 없으면 0개가 정답입니다.
판정법 — 쓸까 말까 3초 안에 가르기
항목 하나를 넣을지 말지는 질문 세 개면 끝납니다.
표로 다시 정리하면 이렇습니다.
| 후보 항목 | 판정 | 이유 |
|---|---|---|
| “src/ 아래에 컴포넌트, utils/ 아래에 헬퍼” | ✕ 지운다 | 폴더 열면 아는 것 |
| “다음 할 일: 결제 모듈 붙이기” | ✕ 메모리로 | 다음 주면 거짓말 |
| “이 빌드 명령만 동작함 (다른 건 서명 에러)” | ✓ 남긴다 | 겪어야 아는 것 |
| “DB 마이그레이션은 반드시 백업 후에 (한 번 날림)” | ✓ 남긴다 | 겪어야 아는 것 |
| “코드는 읽기 쉽게 작성” | ✕ 지운다 | 모델 기본값. 지시 비용만 발생 |
실물 예시 — 이 블로그의 CLAUDE.md
이 블로그 프로젝트의 CLAUDE.md는 3.7KB고, 절반이 함정 목록입니다. 일부만 추려 발췌합니다.
## 함정 (겪어봐야 아는 것)
- 브랜드는 aimake.log(점 있음), 도메인은 aimakelog.app(점 없음) — 의도적 불일치
- 작성자 표시명은 "재박" (재백 아님)
- 썸네일/커버는 16:9 — 비율 강제로 자르면 글자 잘림
- 네이버 인증 파일은 WP 루트에 있음 — 지우면 소유확인 풀림
- 정적 내보내기는 백그라운드 작업이라 healthcheck로 돌려야 함
전부 제가 한 번씩 틀렸거나, 틀리면 복구가 귀찮은 것들입니다. “재박”을 “재백”으로 잘못 바꾼 적이 실제로 있고, 그날 이 줄이 추가됐습니다. CLAUDE.md는 설계 문서가 아니라 흉터의 기록에 가깝습니다.
이미 문서가 있다면 — 복사하지 말고 가리켜라
README나 브랜드 가이드가 이미 있는 프로젝트라면 CLAUDE.md에 같은 내용을 다시 쓰면 안 됩니다. 한쪽만 고쳐지는 순간 두 문서가 서로 다른 말을 하게 되고, 모델은 그 모순을 중재하느라 판단력을 낭비합니다. 지난 점검에서 실제로 나온 충돌 패턴입니다.
처방은 두 가지입니다.
README가 이미 함정 문서 역할을 하고 있다면 — 심링크 한 줄.
# 같은 내용을 두 파일로 만들지 않는다
ln -s README.md CLAUDE.md
이 블로그 프로젝트가 정확히 이 방식입니다. CLAUDE.md는 README를 가리키는 링크일 뿐이고, 고칠 파일은 언제나 하나입니다.
문서가 여러 개라면 — 가리키기만 하는 포인터 파일.
지난 점검에서 “브랜드 가이드를 열심히 써놓고 아무 세션도 안 읽던” 디자인 프로젝트에 만들어준 파일은 781바이트였습니다. 내용은 “브랜드 규칙은 DESIGN.md, 폴더 지도는 구조.md” 두 줄에 함정 세 줄이 전부입니다. 본문을 복사하지 않고 위치만 알려주면, 모델이 필요할 때 알아서 열어봅니다.
쓰면 안 되는 것 — 메모리가 할 일
Claude Code에는 자동 메모리가 있습니다. 세션에서 배운 것을 모델이 스스로 기록하고 다음 세션에 불러오는 기능이죠. 그래서 CLAUDE.md와 역할을 나눠야 합니다.
- CLAUDE.md — 변하지 않는 함정·제약·확정사항. 사람이 관리
- 메모리 — “지금 어디까지 했고 다음이 뭔지” 같은 시점 정보. 모델이 관리
“다음 할 일” 목록을 이 파일에 적는 건 흔하지만 나쁜 습관입니다. 그 줄은 일주일 뒤 확실하게 거짓말이 되고, 지난 점검에서 나온 “남의 맥 경로가 박힌 CLAUDE.md”와 같은 병으로 죽습니다 — 미리 써둔 글은 환경이 바뀌는 순간 부패합니다.
5분 세팅 — 순서대로
# 1. 이미 있는 문서부터 확인 (중복 문서를 만들지 않기 위해)
ls README.md docs/ 2>/dev/null
# 2-a. README가 이미 함정을 담고 있다 → 심링크로 끝
ln -s README.md CLAUDE.md
# 2-b. 문서가 없다 → 빈 파일에서 시작
touch CLAUDE.md
빈 파일이면 됩니다. 처음부터 채우려 하지 말고, 작업하다 모델이 틀리는 순간마다 한 줄씩 추가하세요. “겪어봐야 아는 것”은 정의상 겪기 전에는 쓸 수 없습니다. 제 함정 목록도 전부 그렇게 쌓였습니다.
마지막으로, 남의 저장소를 클론해서 시작했다면 이것 하나만 돌려보세요. 원저자의 로컬 경로가 CLAUDE.md에 박혀 있으면 그 지시는 따를수록 실패합니다.
# 내 것이 아닌 사용자 경로가 박혀 있는지 (결과 없으면 정상)
# grep -r 은 심링크를 건너뛰므로 find 로 넘겨야 한다 — 위에서 권한 심링크 방식도 걸러진다
find . -name CLAUDE.md -exec grep -Hn "/Users/" {} + | grep -v "/Users/$(whoami)/"
정리
- 원칙 — 열어보면 아는 것은 지우고, 겪어봐야 아는 것만 남긴다
- 위치 — 프로젝트 루트가 중심. 글로벌은 세금, 하위폴더는 예외용
- 판정 — 구조 나열은 삭제, 시점 정보는 메모리로, 함정·제약·확정만 파일에
- 중복 금지 — 기존 문서는 복사하지 말고 심링크나 포인터로
- 성장 방식 — 미리 채우지 말고, 틀릴 때마다 한 줄씩
다음 글에서는 컨텍스트에 넣기 어려운 PDF·한글(HWP) 문서를 마크다운으로 바꿔 먹이는 법을 다룹니다.
