Claude Code 메모리 관리 완전 가이드

Auto Memory와 CLAUDE.md의 차이와 활용 전략

Claude Code를 사용하다 보면 “이 설정을 매번 다시 설명해야 하나?”, “프로젝트 규칙을 어떻게 지속적으로 반영할 수 있을까?”라는 고민이 생깁니다. 특히 팀 단위로 협업하거나 여러 프로젝트를 오가며 작업한다면, 일관된 규칙과 맥락 유지가 중요해집니다.

이 글에서는 Claude Code의 메모리 관리 구조를 중심으로 Auto Memory와 CLAUDE.md 파일의 차이, 계층 구조, 로딩 방식, 설정 및 제어 방법까지 체계적으로 정리합니다. 각 메모리 유형이 어떤 목적에 적합한지, 실제 프로젝트에서는 어떻게 활용하면 좋은지도 함께 살펴보겠습니다.

반응형

---

1. Claude Code 메모리 구조 개요

Claude Code는 세션 간 지속되는 두 가지 메모리 방식을 제공합니다.

• Auto Memory
• CLAUDE.md 파일 기반 메모리

두 방식 모두 세션 시작 시 컨텍스트에 로드되지만, 관리 방식과 목적이 다릅니다.

---

2. Auto Memory란 무엇인가

Auto Memory는 Claude가 작업 중 자동으로 학습하고 기록하는 메모리입니다. 사용자가 직접 작성하는 것이 아니라, 프로젝트 패턴과 선호도를 Claude가 스스로 정리합니다.

주요 특징

• 프로젝트 패턴 자동 저장 (빌드 명령어, 테스트 방식 등)
• 디버깅 인사이트 기록
• 아키텍처 메모 작성
• 사용자 작업 스타일 및 선호도 반영
• 프로젝트 단위 개별 저장

저장 위치

Auto Memory는 다음 경로에 저장됩니다.

~/.claude/projects//memory/

구조 예시:

• MEMORY.md (세션 시작 시 상위 200줄 자동 로드)
• debugging.md
• api-conventions.md
• 기타 토픽 파일

중요한 점은 MEMORY.md의 상위 200줄만 자동 로드된다는 것입니다. 따라서 핵심 내용은 간결하게 유지하고, 상세 내용은 별도 파일로 분리하는 것이 효율적입니다.

Auto Memory 제어 방법

1. /memory 명령어로 토글 가능
2. 설정 파일에서 비활성화 가능

사용자 전체 비활성화:

~/.claude/settings.json

{
"autoMemoryEnabled": false
}

프로젝트 단위 비활성화:

.claude/settings.json

{
"autoMemoryEnabled": false
}

환경 변수로 강제 제어:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

CI 환경이나 보안이 중요한 환경에서는 환경 변수 기반 제어가 유용합니다.

---

3. CLAUDE.md 파일 기반 메모리

CLAUDE.md는 사용자가 직접 작성하는 지침 파일입니다. 조직 정책, 프로젝트 표준, 개인 선호도를 명확하게 정의할 수 있습니다.

계층 구조

Claude Code는 현재 작업 디렉토리에서 상위 디렉토리로 재귀 탐색하며 CLAUDE.md 파일을 로드합니다. 더 구체적인 위치의 파일이 우선 적용됩니다.

메모리 유형별 위치와 목적

1. Managed Policy
   조직 전체 공통 규칙
   예: 회사 코딩 표준, 보안 정책
2. Project Memory
   ./CLAUDE.md 또는 ./.claude/CLAUDE.md
   팀 공유 프로젝트 규칙
3. Project Rules
   ./.claude/rules/*.md
   모듈형 세부 규칙
4. User Memory
   ~/.claude/CLAUDE.md
   개인 전역 설정
5. Project Local Memory
   ./CLAUDE.local.md
   개인 프로젝트 전용 설정 (자동 gitignore 처리)

---

4. .claude/rules를 활용한 모듈형 규칙 관리

대규모 프로젝트에서는 하나의 CLAUDE.md에 모든 규칙을 작성하는 대신, .claude/rules/ 디렉토리를 활용하는 것이 좋습니다.

예시 구조:

.claude/rules/

• code-style.md
• testing.md
• security.md

각 파일은 하나의 주제만 다루는 것이 이상적입니다. 예를 들어 testing.md에는 테스트 규칙만 작성합니다. 이렇게 하면 유지보수성과 가독성이 크게 향상됩니다.

---

5. Path 기반 조건부 규칙

YAML frontmatter의 paths 필드를 활용하면 특정 파일에만 규칙을 적용할 수 있습니다.

예시:

---

paths:

• "src/api/**/*.ts"

---

이 규칙은 src/api 하위의 TypeScript 파일에만 적용됩니다.

지원 패턴 예시:

• **/*.ts
• src/**/*
• src/**/*.{ts,tsx}
• {src,lib}/**/*.ts

프론트엔드, 백엔드, 테스트 코드별로 정책을 세분화할 수 있어 복잡한 프로젝트에서 매우 유용합니다.

---

6. CLAUDE.md Import 기능

CLAUDE.md 파일에서는 @경로 형식으로 외부 파일을 불러올 수 있습니다.

예시:

See @README

• git workflow @docs/git-instructions.md

상대 경로는 해당 파일 기준으로 해석됩니다.

주의 사항:

• 코드 블록 안에서는 import가 동작하지 않음
• 최대 5단계 재귀 import 지원
• 최초 외부 import 사용 시 승인 필요

공통 규칙 파일을 여러 프로젝트에서 재사용할 때 매우 효율적입니다.

---

7. Auto Memory와 CLAUDE.md의 차이 정리

Auto Memory는 Claude가 작업 중 학습한 경험을 기록하는 자동 메모입니다.

CLAUDE.md는 사용자가 명시적으로 정의하는 정책 문서입니다.

Auto Memory는 “패턴 축적”에 강점이 있고,
CLAUDE.md는 “규칙 정의”에 강점이 있습니다.

두 방식을 함께 사용하는 것이 가장 이상적인 운영 방식입니다.

---

728x90

Claude Code의 메모리 구조는 단순한 설정 저장 기능이 아닙니다. 조직, 팀, 개인 단위의 지식과 규칙을 체계적으로 관리하는 구조입니다.

Auto Memory를 통해 작업 패턴을 자동 축적하고, CLAUDE.md로 명확한 규칙을 정의하면 반복 설명 없이도 일관된 개발 환경을 유지할 수 있습니다.

대규모 레포지토리, 멀티 워크트리 환경, 보안 요구가 높은 조직에서는 특히 메모리 계층 구조 설계가 생산성에 직접적인 영향을 줍니다.

지금 사용 중인 프로젝트에 CLAUDE.md가 없다면 /init 명령으로 시작해 보시기 바랍니다. 이는 단순한 문서 작성이 아니라, 장기적인 개발 생산성을 설계하는 작업이 될 것입니다.

300x250

https://code.claude.com/docs/en/memory?media_id=3841383354827276055_66161159209&media_author_id=66161159209&ranking_info_token=GCBhMWM0Y2MzNzIzODg0YWNmYTE5MTE3MjQ2YTI5MDExZCW+3foBJubxh5oNGBMzODQxMzgxOTIzNzM5MDc2NTQ5KANjY28A&utm_source=ig_text_post_permalink&fbclid=IwY2xjawQOJbZleHRuA2FlbQIxMQBzcnRjBmFwcF9pZBAyMjIwMzkxNzg4MjAwODkyAAEeSn35ZaW5FObJ1QRqRmnUBmYoyinZR62dQ_Ki2gC07Lfgrd92CaExcAOFeiQ_aem_7GftA7Dx3-NfZRJ981CZAA

Manage Claude's memory - Claude Code Docs