CLAUDE.md는 에이전트가 일을 시작하기 전에 읽는 집 안내서야
CLAUDE.md에는 매번 첫 메시지로 설명하기 아까운 장기 진실을 적어. 기술 구성, 자주 쓰는 명령, 아키텍처 원칙, 절대 어기면 안 되는 제약이 여기에 들어가. 대화가 아니라 저장소와 함께 버전 관리되기 때문에 새 세션도 같은 규칙을 물려받아.
전역 ~/.claude/CLAUDE.md에는 개인 습관을, 저장소 루트에는 팀 공통 규칙을, 더 깊은 디렉터리에는 그 영역만의 추가 규칙을 둬. 적용되는 문서는 모두 합쳐지고 작업 위치에 가까운 규칙이 더 구체적인 사정을 덧붙여. 결제 코드만 특별히 엄격하게 다루는 식의 구성이 복사 없이 가능하지.
처음부터 빈 문서를 붙잡고 쓸 필요도 없어. /init이 저장소를 훑어 초안을 만들면 틀린 부분을 덜어내고 빠진 원칙을 보태. 세션 도중 새로 배운 사실은 메시지 앞에 #를 붙여 적절한 CLAUDE.md에 남길 수도 있어.
직접 확인할 항목: package.json, pyproject.toml, src/.../CLAUDE.md.