Claude Code를 프로젝트에 붙여 쓰다 보면 두 가지 요구가 생깁니다. “이 규칙은 매번 지켜라”와 “지난번에 알아낸 걸 기억해라”.
앞의 것을 담당하는 게 룰 파일인 CLAUDE.md이고 뒤의 것을 담당하는 게 메모리 기능입니다. 둘 다 “세션이 끝나도 남는 지시”라서 헷갈리기 쉬운 부분인데, 관리 주체와 성격이 다릅니다.
이 글에서는 CLAUDE.md의 계층 구조, 메모리 기능의 동작 방식, 그리고 어떤 내용을 어디에 둬야 하는지 기준까지 정리합니다.
핵심 요약부터 보고 갈게요.
- CLAUDE.md는 매 세션 자동으로 로드되는 룰 파일이고, 전역·프로젝트 단위로 계층이 나뉩니다
- 메모리는 Claude가 작업하며 알게 된 사실을 프로젝트별 폴더에 스스로 기록·회수하는 기능입니다
- 사람이 정한 규칙은 CLAUDE.md, 에이전트가 축적한 경험은 메모리로 갈립니다
- 둘 다 컨텍스트를 소비하므로 “항상 필요한가?“를 기준으로 슬림하게 유지해야 합니다
CLAUDE.md, 위치가 곧 적용 범위
CLAUDE.md는 세션이 시작될 때 프롬프트에 통째로 올라가는 마크다운 파일입니다. 코딩 컨벤션, 금지 사항, 프로젝트 배경처럼 “항상 참이어야 하는 규칙”을 담습니다.
같은 이름의 파일이라도 위치에 따라 적용 범위가 다릅니다.
| 위치 | 범위 | 공유 |
|---|---|---|
| ~/.claude/CLAUDE.md | 모든 프로젝트 | 개인 전용 |
| 프로젝트/CLAUDE.md | 해당 프로젝트 | git으로 팀 공유 |
| 하위폴더/CLAUDE.md | 그 폴더 작업 시 | git으로 팀 공유 |
전역 파일에는 프로젝트와 무관한 개인 취향(커밋 스타일, 응답 언어)을, 프로젝트 파일에는 저장소 고유의 규칙을 둡니다. 두 계층이 충돌하면 보통 더 구체적인 쪽, 즉 프로젝트 규칙이 우선하도록 명시해 두는 게 안전합니다.
파일이 길어지면 @경로/파일.md 형태로 다른 문서를 임포트해 쪼갤 수도 있습니다. 다만 임포트된 문서도 결국 컨텍스트에 올라간다는 점은 같아서, 분량 절약이 아니라 관리 편의를 위한 기능이라고 보는 게 맞습니다.
메모리, 에이전트가 스스로 쓰는 노트
CLAUDE.md가 사람이 작성하는 하향식 규칙이라면, 메모리는 반대 방향입니다. Claude가 작업 중 알게 된 사실을 프로젝트별 메모리 폴더에 파일로 기록해 두고, 다음 세션에서 다시 꺼내 씁니다.
동작 구조는 단순합니다. 메모리 하나가 파일 하나이고 인덱스 파일(MEMORY.md)에 한 줄 요약이 쌓입니다. 세션 시작 시 인덱스만 컨텍스트에 올라가고 개별 메모리의 본문은 관련 작업을 할 때 읽는 식이에요.
기록되는 내용의 결도 룰과 다릅니다. “이 DB는 배치 후 타입 검사가 필요하더라”, “dev 서버는 이 워크트리에서 띄워야 반영되더라” 같은, 문서엔 없지만 겪어봐야 아는 사실들입니다. 사람이 규칙으로 명문화하기 전 단계의 경험 지식이 쌓이는 셈이죠.
대화 중에 #으로 시작하는 메시지를 보내 “이거 기억해 둬”라고 직접 지시할 수도 있습니다. 이 경우 Claude가 어느 파일에 저장할지 물어보거나 알아서 분류합니다.
어디에 둘지 가르는 기준
둘의 역할이 겹쳐 보일 때는 세 가지 질문으로 가릅니다.
첫째, 누가 결정한 내용인가. 팀이나 본인이 정한 규칙이면 CLAUDE.md, 작업하다 발견한 사실이면 메모리입니다.
둘째, 어겼을 때 문제가 되는가. 위반이 곧 사고인 규칙(비밀키 커밋 금지, 배포 절차)은 반드시 CLAUDE.md에 둡니다. 메모리는 회수가 보장되는 강제 장치가 아니라 참고 노트에 가깝기 때문입니다.
셋째, 코드나 문서로 이미 알 수 있는가. 저장소만 읽어도 알 수 있는 내용은 어느 쪽에도 넣지 않는 게 원칙입니다. 컨텍스트만 낭비하고, 코드가 바뀌면 거짓 정보가 됩니다.
운영하며 지킬 것 두 가지
첫째, 정기적으로 비우기. CLAUDE.md는 규칙이 쌓이기만 하고 지워지진 않는 경향이 있습니다. 더는 유효하지 않은 규칙, 한 번 쓰고 만 지시는 발견 즉시 삭제해야 매 세션의 컨텍스트 낭비를 막을 수 있어요. 메모리도 마찬가지로, 코드가 바뀌어 사실이 아니게 된 항목은 지우는 게 남기는 것보다 낫습니다.
둘째, 규칙은 짧고 단정적으로. “가능하면 ~하는 게 좋습니다” 같은 문장보다 “~한다, ~금지” 같은 단문이 잘 지켜집니다. 예시 한 줄을 붙이면 준수율이 눈에 띄게 올라갑니다.
마무리
CLAUDE.md는 헌법이고 메모리는 업무 일지입니다. 사람이 정한 불변 규칙은 위에서 내려보내고, 현장에서 얻은 경험은 아래에서 쌓아 올리는 구조죠.
이 둘을 구분해서 관리하기 시작하면, 매 세션 같은 설명을 반복하는 일도, 지난 세션의 삽질을 다시 겪는 일도 줄어듭니다.