CLAUDE.md와 auto memory의 차이점 및 작성 방법

이 글을 통해 알 수 있는 것

• Claude Code에는 '작성 기억'과 '기억하는 기억' 두 가지 메커니즘이 있다는 점
• CLAUDE.md 파일의 역할과 위치별 사용 구분
• auto memory란 무엇인지, 활성화/비활성화 방법, 저장 위치
• 오늘부터 실천할 수 있는 CLAUDE.md 작성 요령

결론: Claude Code에는 '작성 기억'과 '기억하는 기억'이 있다

Claude Code는 세션을 시작할 때마다 백지 상태에서 출발합니다. 그럼에도 불구하고 이전까지의 지식을 이어받을 수 있는 것은 두 가지 메커니즘 덕분입니다.

• CLAUDE.md 파일: 사용자가 직접 작성하는 지시사항. 프로젝트의 방향성이나 규칙을 전달함 -
• auto memory: Claude가 지적이나 선호도에 따라 자동으로 기록하는 학습 내용

두 가지 모두 세션 시작 시 로드되지만, '누가 작성하느냐'가 완전히 다릅니다.

다이어그램으로 표현하면 다음과 같습니다.

CLAUDE.md란 무엇인가? 어디에 두어야 할까?

CLAUDE.md는 프로젝트나 개인의 작업 방침을 Claude에게 전달하기 위한 Markdown 파일입니다. 놓는 위치에 따라 스코프(누구와 공유되는지)가 달라집니다.

먼저 용어를 확인하자: '홈 디렉토리'와 '작업 디렉토리'란?

위치에 대해 이야기하기 전에, 두 가지 단어만 알아두겠습니다.

• 홈 디렉토리 (Home Directory): 사용자 본인 전용 폴더를 말합니다. Mac의 경우 ~
  ）/Users/사용자명<br>Windows의 경우 C:\Users\사용자명``이 이에 해당합니다. ~는 이 폴더를 가리키는 약어입니다.
• 작업 디렉토리 (Working Directory): 현재 작업하고 있는 프로젝트 폴더를 말합니다. 터미널에서 cd my-app으로 이동한 곳, 즉 'Claude Code를 실행했을 때 그곳에 있던 폴더'라고 생각하시면 됩니다.

즉, 홈 디렉토리 = 사용자 전용 공간, 작업 디렉토리 = 현재 프로젝트의 공간이라는 두 개의 상자가 있는 이미지입니다.

작업 디렉토리 자체와 그 상위에 있는 CLAUDE.md, CLAUDE.local.md는 실행 시 한 번에 로드됩니다. 서브디렉토리에 있는 파일은 Claude가 해당 파일을 읽는 타이밍에 추가로 로드됩니다.

단어만으로는 상상하기 어려우므로, '홈 디렉토리 안에 작업 디렉토리(프로젝트 폴더)가 있다'라는 하나의 다이어그램으로 정리합니다 (관리 정책은 프로젝트 외부에 OS별 고정 경로에 놓이므로 아래 그림에는 포함하지 않았습니다).

/Users/사용자명/ ← 홈 디렉토리(~) 
├── .claude/
│ └── CLAUDE.md ← 사용자용 (자신의 모든 프로젝트 공통)
...

즉, 사용자용은 홈 디렉토리 안에, 나머지 세 가지는 작업 디렉토리(프로젝트 폴더) 안에 기억해 두시면 됩니다.

초안을 자동 생성하고 싶을 때

/init

명령어를 실행하면 Claude가 코드베이스를 분석하여 CLAUDE.md의 초안을 자동으로 생성합니다. 이미 CLAUDE.md가 있는 경우, 덮어쓰기 대신 개선안을 제안해 줍니다.

auto memory란?

auto memory는 Claude가 스스로 판단하여 '이것은 기억해 두면 유용하다'고 생각한 내용을 기록하는 메커니즘입니다. 아무것도 작성하지 않아도, Claude가 지적이나 선호도에 따라 학습합니다.

기록되는 내용은 다음 4가지로 분류됩니다.

user: 당신의 역할・전문성・작업 선호도
feedback: 당신이 수행한 수정 사항이나, 확인된 진행 방식
project: 코드나 git 히스토리에서는 파악할 수 없는, 진행 중인 작업이나 결정 사항
reference: 과제 관리 툴이나 대시보드 등, 프로젝트 외부 정보의 위치

코드에서 읽을 수 있는 것과 CLAUDE.md에 이미 작성된 내용은 기록하지 않습니다.

유효/무효 전환 및 저장 위치

auto memory는 기본적으로 활성화되어 있습니다. 세션 내에서 /memory를 열면 토글할 수 있습니다(설정은 ~/.claude/settings.json의 autoMemoryEnabled에 저장됩니다). 프로젝트 단위로 비활성화하고 싶다면, 해당 프로젝트 설정 파일에서 autoMemoryEnabled를 지정합니다.

저장 위치는 프로젝트별 전용 디렉토리(~/.claude/projects/<project>/memory/)입니다. 저장 위치를 변경하고 싶다면 autoMemoryDirectory라는 설정 키로 지정할 수 있습니다.

디렉토리의 내용은 다음과 같은 구성이 됩니다.

~/.claude/projects/<project>/memory/
├── MEMORY.md ← 인덱스. 1행 1메모리로, 매 세션 로드됨
├── user_role.md ← 개별 메모리 파일 (예)
...

MEMORY.md는 세션 시작 시 반드시 로드되지만, 행 수나 크기에 제한이 있기 때문에 상세 내용은 개별 토픽 파일에 맡기고 인덱스는 간결하게 유지하는 설계입니다.

CLAUDE.md와 auto memory, 무엇이 다른가?

오늘부터 할 수 있는 작성 요령

CLAUDE.md는 대화 시작 시 메시지로 전달될 뿐, 강제되는 규칙은 아닙니다. 따라서 작성 방식에 따라 효과가 달라집니다.

• 구체적으로 작성하기 : '코드를 제대로 포맷해 줘' 대신 '들여쓰기는 공백 반 칸 두 개'처럼 검증 가능한 형태로 만듭니다.
• 간결하게 유지하기: 적정 분량은 200행 정도입니다. 너무 길어지면 오히려 지시를 따르는 정확도가 떨어집니다.
• 모순을 방치하지 않기: 여러 CLAUDE.md나 지시가 서로 상충하면, Claude가 어느 것에 따라야 할지는 일정하지 않습니다.

CLAUDE.md에 무엇을 추가할지 고민될 때의 판단 기준으로는 다음과 같은 시점이 언급됩니다.

• Claude가 같은 실수를 두 번째 했을 때
• 코드 리뷰에서 이 프로젝트 특유의 주의점이 발견되었을 때
• 지난 세션과 동일한 설명/수정을 또 입력하고 있을 때

요약

• CLAUDE.md는 '스스로 작성하는 지시', auto memory는 'Claude가 자동으로 기록하는 학습'이라는 역할 차이가 있습니다.
• CLAUDE.md는 위치에 따라 공유 범위가 달라집니다 (조직/본인 전용/팀 공유/개인 프로젝트 전용).
• auto memory는 기본적으로 활성화되어 있습니다.
  /memory
  로 확인 및 전환이 가능하며, 저장 위치도 변경할 수 있습니다 - 같은 수정을 두 번 했다는 시점이 CLAUDE.md에 추가하기 좋은 기준이 됩니다.

우선은 CLAUDE.md로 기본적인 방침을 작성하고, 세부적인 학습은 auto memory에 맡겨서 키워나가는 사용법부터 시작해 보세요.

참고 자료

• How Claude remembers your project — CLAUDE.md와 auto memory의 정의, 위치, 유효/무효 전환, 저장 위치에 대한 1차 정보
• Settings reference —
  autoMemoryEnabled
  ・autoMemoryDirectory
  라는 설정 키 이름의 1차 정보
  본 기사 작성에는 AI 도구를 활용했습니다. 정보의 정확성에는 주의를 기울였으나, 최신 정보는 공식 문서를 함께 확인해 주십시오.

Discussion