Claude Code를 쓰다 보면 "CLAUDE.md"라는 파일 이름을 자주 만납니다. 어렵게 들리지만, 이건 한마디로 "Claude에게 매번 다시 설명하기 귀찮은 것들을 한 번 적어두는 안내문"입니다. 마치 새 팀원에게 건네는 업무 안내서처럼요. 이 글은 CLAUDE.md가 무엇이고 무엇을 적는지를 쉽게 설명합니다.
CLAUDE.md가 뭐예요? (한 문장 정의)
CLAUDE.md는 프로젝트나 내 작업 방식에 대한 '지속적인 안내'를 담은 마크다운 파일입니다. 여기서 "마크다운"은 그냥 평범한 글로 쓰는 텍스트 파일이라고 보면 됩니다(특별한 코딩이 필요 없어요). 가장 중요한 점은, Claude Code가 매 세션을 시작할 때 이 파일을 자동으로 읽는다는 것입니다.
왜 필요한가요?
Claude Code는 새 대화(세션)를 시작할 때마다 빈 상태로 출발합니다. 어제 알려준 프로젝트 구조나 규칙을 오늘은 기억하지 못하죠. 그래서 CLAUDE.md가 없으면 매번 "우리 프로젝트는 이렇게 생겼고, 빌드는 이 명령으로 하고, 이런 규칙을 지켜줘"를 반복해서 설명해야 합니다. 마치 매일 아침 신입을 처음부터 다시 교육하는 셈입니다.
CLAUDE.md에 한 번 적어두면, Claude가 세션 시작 때 자동으로 읽으므로 같은 설명을 반복할 필요가 없어집니다.
무엇을 적나요?
핵심 기준은 간단합니다. "매번 다시 설명하게 되는 것"을 적는다. 공식 문서는 다음과 같은, 모든 세션에서 알고 있어야 할 사실들을 권합니다.
- 빌드·실행 명령 — 자주 쓰는 명령(예: 개발 서버 실행 명령).
- 프로젝트 구조 — 폴더 구성, 어디에 무엇이 있는지.
- 코딩 규칙·컨벤션 — 들여쓰기, 이름 짓는 방식, 스타일 약속.
- '항상 ~하라' 규칙 — "항상 테스트를 먼저", "답변은 한국어로" 같은 고정 규칙.
- 피해야 할 것 — 건드리면 안 되는 파일이나 금지할 동작.
반대로, 여러 단계를 거치는 복잡한 절차나 코드의 특정 부분에만 해당하는 내용은 CLAUDE.md 대신 스킬(Skill)이나 범위를 좁힌 규칙으로 옮기는 것이 좋습니다. CLAUDE.md는 길어질수록 지저분해지므로 대략 50~200줄로 간결하게 유지하길 권합니다.
어디에 두나요? (위치 계층)
CLAUDE.md는 여러 위치에 둘 수 있고, 각 위치는 적용 범위가 다릅니다. 공식 문서 기준 대표적인 계층은 다음과 같습니다.
- 조직 정책(Enterprise) — 회사 전체에 적용되는 규칙. IT/관리자가 관리합니다.
- 프로젝트(
./CLAUDE.md) — 그 프로젝트 팀이 공유하는 안내. 보통 소스 코드에 함께 포함됩니다. - 개인(
~/.claude/CLAUDE.md) — 내 모든 프로젝트에 적용되는 개인 취향. 나만 봅니다.
여러 파일이 있으면 상위(넓은 범위) 파일이 먼저 로드되어 토대가 되고, 더 구체적인 파일이 그 위에 더해집니다. 중요한 점: CLAUDE.md는 강제 설정이 아니라 '맥락'으로 취급됩니다. 즉 Claude가 참고하는 안내이지, 무조건 차단하는 장치가 아닙니다. 그래서 구체적이고 간결하게 쓸수록 더 일관되게 지켜집니다.
간단한 예시
처음이라면 이렇게 짧게 시작해도 충분합니다.
# 프로젝트 안내
## 명령
- 개발 서버: npm run dev
- 테스트: npm test
## 규칙
- 항상 테스트를 먼저 작성
- 설명과 주석은 한국어로
- src/legacy 폴더는 수정 금지처음부터 완벽하게 채울 필요 없습니다. 작업하다 "이거 또 설명하네" 싶은 게 생기면 그때그때 한 줄씩 추가하면 됩니다.
정리
CLAUDE.md는 어려운 설정 파일이 아니라 "매번 다시 설명하기 귀찮은 것을 적어두는 안내문"입니다. Claude가 매 세션 자동으로 읽고, 빌드 명령·구조·규칙 등을 담으며, 위치에 따라 적용 범위가 달라집니다. 바로 쓸 수 있는 템플릿이 필요하면 같은 사이트의 CLAUDE.md 템플릿 모음과 프로젝트 유형별 예시를 이어서 보세요.
본 글은 Anthropic 공식 문서(code.claude.com/docs, docs.anthropic.com)의 공개 정보를 초보자용으로 풀어 정리했습니다. 파일 위치·동작은 제품 업데이트로 바뀔 수 있으니 실제 사용 시 공식 문서를 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.