CLAUDE.md의 역할과 구조

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽어 들이는 마크다운 파일이다. 시스템 프롬프트에 직접 끼워 넣는 별도의 지시문이 아니라, 에이전트의 "프로젝트 기억"으로 작동한다. 사용자가 평문으로 작성하면 Claude가 세션 시작마다 컨텍스트에 적재하므로, 매번 같은 지시를 반복할 필요가 없다. 빌드 명령, 코드 스타일, 디렉터리 구조, 금지 사항, 워크플로우 규칙 같은 항목이 전형적인 내용이다.

여기서 반드시 구분해야 할 두 가지 메모리 시스템이 있다. 첫째는 사용자가 직접 작성하는 CLAUDE.md(지시형 메모리)이고, 둘째는 Claude가 작업 중 스스로 축적하는 auto memory(자동 메모리)다. auto memory는 사용자의 교정·선호를 학습해 빌드 명령이나 아키텍처 노트를 자체적으로 기록하며 기본값으로 켜져 있다. 세션 안에서 /memory 명령으로 토글하거나 프로젝트 설정의 autoMemoryEnabled로 제어한다. 시험은 "CLAUDE.md는 사람이 쓰고, auto memory는 Claude가 쓴다"는 출처 구분을 묻는다.

메모리 로드 위치와 계층

CLAUDE.md는 여러 위치에 둘 수 있고 각 위치는 스코프가 다르다. 세션 시작 시 다음이 함께 로드된다.

• 조직 정책 CLAUDE.md(enterprise managed policy): IT/DevOps가 배포하며 개인 설정으로 제외할 수 없다.
• 프로젝트 CLAUDE.md(./CLAUDE.md): 소스 관리에 포함되어 팀과 공유된다.
• 사용자 CLAUDE.md(~/.claude/CLAUDE.md): 모든 프로젝트에 적용되는 개인 전역 메모리.
• 하위 디렉터리의 CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, 그리고 CLAUDE.local.md도 함께 적재된다.

CLAUDE.local.md는 여전히 로드되지만, --setting-sources에서 local을 제외하면 건너뛴다. 시험 함정 하나: "CLAUDE.local.md는 완전히 제거되었다"는 진술은 틀리다. 로드되되 local 소스 제외 시 생략되는 것이다.

@import로 파일 분리하기

CLAUDE.md 안에서 @경로 구문으로 다른 파일을 가져올 수 있다. 예를 들어 @docs/coding_style.md처럼 쓰면 해당 파일 내용이 포함된다. 이는 가독성과 조직화에는 좋지만 컨텍스트를 줄이지는 못한다는 점이 핵심이다. import된 파일은 세션 시작 시 모두 함께 로드되므로, 큰 규칙을 여러 파일로 쪼개도 적재되는 총 토큰은 동일하다. 시험은 "@import가 컨텍스트 사용량을 줄여 준다"는 흔한 오해를 함정으로 낸다. 실제 효과는 유지보수성·재사용성 향상이지 토큰 절감이 아니다.

작성 원칙

좋은 CLAUDE.md는 짧고 구조적이며 행동 가능한 지시로 구성된다. 모든 작업에 공통으로 적용되는 핵심 규칙만 본문에 두고, 세부 규칙은 별도 파일로 분리해 경로로 참조하는 Progressive Disclosure 패턴이 권장된다. 장황한 배경 설명보다 명령형의 규칙 목록이 효과적이며, 충돌하거나 모호한 지시는 예측 불가능한 동작을 부른다. 작성·갱신은 /init로 초기 생성하거나 /memory로 편집한다.

정리

• CLAUDE.md는 사람이 작성하는 지시형 메모리이고, auto memory는 Claude가 스스로 축적하는 자동 메모리다. 둘은 모두 세션 시작 시 로드된다.
• 로드 위치는 조직 정책, 프로젝트(./CLAUDE.md), 사용자(~/.claude/CLAUDE.md), 하위 디렉터리, .claude/rules/*.md, CLAUDE.local.md 등 여러 스코프로 나뉜다.
• CLAUDE.local.md는 폐기되지 않았다. 여전히 로드되며 local 소스를 제외할 때만 생략된다.
• @import는 파일을 분리해 가독성을 높이지만 컨텍스트 토큰을 줄이지 않는다. import 파일은 시작 시 전부 적재된다.
• 핵심 규칙만 본문에 두고 세부는 분리해 참조하는 Progressive Disclosure가 권장 설계 패턴이다.