Claude Code에서 CLAUDE.md와 auto memory를 구분하여 사용해야 하는 이유

이 글은 playpark Blog에서 전재된 내용입니다.

• CLAUDE.md와 auto memory 각각을 어떻게 구분하여 사용해야 하는지에 대한 이유

./.claude/rules/

・Skills, hooks를 포함한 선택지와의 비교 - 어떤 내용을 어디에 배치해야 할지에 대한 판단 기준

Claude Code에는 세션을 넘나들며 지식을 보존하는 두 가지 메커니즘이 있습니다. 개발자가 작성하는 '규칙 문서'인 CLAUDE.md와 Claude 스스로가 작성하는 '학습 노트'인 auto memory입니다. 둘 다 '기억'처럼 보이기 때문에, 'auto memory가 있으니 더 설명할 필요가 없을 것 같다'고 기대하기 쉽습니다. 하지만 누가 작성하고, 언제 읽히며, 누구에게 전달되는지가 완전히 다릅니다. 이 점을 파악하지 못하면, 기억되기를 바라는 것이 CLAUDE.md에 쌓이고, 지켜지기를 바라는 것이 memory에 맡겨져서 '말했던 것 같은데'가 일상적으로 발생하게 됩니다.

Claude Code에서 지식을 보존하는 수단은 실질적으로 네 가지입니다.

CLAUDE.md는 4단계로 읽히며, 위에서부터 순서대로 적용됩니다. 조직 IT 부서가 관리하는 정책(managed policy), 사용자 개인의 ~/.claude/CLAUDE.md, 리포지토리에 들어갈 프로젝트용 .gitignore 대상의 로컬용입니다.

auto memory는 Claude가 '보존할 가치가 있다'고 판단했을 때만 작성됩니다. 자동으로 남는 것은 역할・취향(user), 수정 이력(feedback), 진행 중인 작업(project), 외부 정보의 위치(reference) 네 가지 종류입니다.

판단 기준은 두 가지로 좁혀집니다. '팀에게도 지켜지게 하고 싶은가'와 '특정 경로나 단계 절차에 연결되는가'입니다.

• 팀 공유가 필요 → git에 넣는다.
  CLAUDE.md. 경로 한정이라면 ./.claude/rules/,
  여러 단계의 절차라면 Skills - 자신만의 역할・취향・진행 중인 작업 →
  auto memory에 맡긴다.
  확실히 남기고 싶은 것만 CLAUDE.local.md에 직접 작성한다 - 생략되면 곤란한 처리 → CLAUDE.md에만으로는 부족하여, hooks로 기계적으로 강제해야 한다.

CLAUDE.md도 auto memory도 Claude가 참조하는 '컨텍스트'일 뿐, 강제력을 가진 메커니즘은 아닙니다. 이 전제를 벗어나면, '테스트 전에 반드시 타입 체크'와 같은 절대 조건을 CLAUDE.md에 적어놓는 것만으로 만족하고 실행을 보장할 수 없게 됩니다.

팀 개발에서 머신 로컬성이 방해가 되는 상황에서는 명시적으로 비활성화할 수 있습니다.

// ./.claude/settings.json
{
"autoMemoryEnabled": false
...
}

환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1,
세션 중의 /memory 토글로도 막을 수 있습니다. /memory는 CLAUDE.md・CLAUDE.local.md・auto memory의 저장 위치를 일람하고, 파일을 선택하여 에디터에서 열 수 있는 관리 화면이기도 합니다.

auto memory의 내용은 코드 변경과 동기화되지 않는다는 점에도 주의해야 합니다. 명령어 이름을 변경해도, memory에 남아있는 오래된 추천은 그대로 남아있을 수 있습니다. 코드로부터 도출할 수 있는 사실은 애초에 memory에 적합한 정보가 아닙니다.

CLAUDE.md와 auto memory는 충돌하는 메커니즘이 아니라, '누가 작성하는지', '누구에게 전달되는지'에 따라 역할이 나뉘어 있습니다. 팀에게 전하고 싶은 규약이나 명령어는 CLAUDE.md로, 자신만의 역할이나 진행 중인 작업은 auto memory로, 생략되면 곤란한 처리는 hooks로 — 이렇게 라우팅을 정해두면 '어디에 써야 할지' 고민하는 시간이 줄어듭니다.

이 글에서는 CLAUDE.md와 auto memory의 사용 구분 이유를 설명했습니다.

Claude Code에서 '기억시키기'와 '지키게 하기' — auto memory와 CLAUDE.md의 사용법 구분하기 더 나아가:

• CLAUDE.md, rules, auto memory, Skills 4가지를 가로로 비교한 표
• '매번 다시 말하는 것을 어디에 둘지'를 판단하기 위한 분기 흐름도
• 실제로 자주 발생하는 3가지 잘못된 배치 패턴과 그 수정 방법

을 다루고 있습니다.

playpark LLC - 업무 자동화・AI 활용・웹 개발