Claude Code가 세션 시작 시 자동으로 읽는 프로젝트 설정 파일. 코드만으로는 알 수 없는 규칙 — 빌드 명령, 코딩 컨벤션, 아키텍처 결정 — 을 담는다.
프로젝트 루트에 CLAUDE.md 파일을 두면 Claude Code가 매 세션 시작 시 자동으로 읽어서 시스템 프롬프트에 포함시킨다. 코드를 아무리 읽어도 알 수 없는 것들 — "테스트는 이렇게 돌려", "이 폴더는 건드리지 마", "커밋 메시지는 한국어로" — 을 여기에 적는다.
프로젝트 루트의 ./CLAUDE.md와 전역 ~/.claude/CLAUDE.md 두 계층이 있다. 프로젝트별 빌드 명령, 코딩 컨벤션, 금지 사항은 프로젝트 파일에, 모든 프로젝트에 공통인 규칙은 전역 파일에 넣는다.
가장 효과적인 패턴은 작업하면서 점진적으로 키워 나가는 것이다. Claude가 실수할 때마다 "이건 이렇게 해"라고 알려주면서 CLAUDE.md에 추가하면, 시간이 지날수록 에이전트가 프로젝트를 더 잘 이해하게 된다. 하네스 엔지니어링의 첫 번째 레이어로, 에이전트에게 맥락과 제약을 주는 가장 기본적인 방법이다.