Claude Code Memory 완벽 가이드: 세션을 넘어 이어지는 AI 컨텍스트

Claude Code를 쓰다 보면 매 세션마다 같은 설명을 반복하게 됩니다. “이 프로젝트는 pnpm을 씁니다”, “테스트는 Vitest로 돌립니다”, “커밋 메시지는 한글로 작성합니다”… Memory는 이 반복을 없애줍니다. 한 번 알려주면 다음 세션부터 Claude가 기억합니다.

이 글에서는 Claude Code Memory의 계층 구조, 각 메모리 타입의 역할, 그리고 실전에서 효과적으로 활용하는 방법까지 단계별로 살펴보겠습니다.

🧠 Memory란?

Memory는 Claude Code가 세션 간에 컨텍스트를 유지하는 시스템입니다. 크게 두 가지로 나뉩니다.

CLAUDE.md는 “이렇게 해줘”라고 미리 적어두는 매뉴얼이고, 자동 메모리는 Claude가 작업하면서 스스로 쌓아가는 경험 노트입니다.

📂 Memory의 계층 구조

Memory는 6개 계층으로 구성됩니다. 조직 전체부터 프로젝트 로컬까지, 범위가 넓은 것부터 좁은 것 순으로 로드됩니다. 더 구체적인 지침이 더 광범위한 지침보다 우선합니다.

전체 계층 한눈에 보기

계층별 상세 설명

관리 정책 — 조직의 IT/DevOps 팀이 MDM이나 Ansible 등으로 중앙 배포하는 지침입니다. 개별 사용자가 직접 수정할 일은 거의 없습니다.

사용자 메모리 (~/.claude/CLAUDE.md) — 모든 프로젝트에 적용되는 개인 기본 설정입니다. “커밋 메시지는 한글로”, “들여쓰기는 2칸” 같은 범용적인 선호도를 여기에 적습니다.

사용자 규칙 (~/.claude/rules/*.md) — 모든 프로젝트에 적용되는 개인 규칙 파일입니다. 주제별로 분리하여 관리할 수 있으며, 아래 “모듈식 규칙” 섹션에서 자세히 다룹니다.

프로젝트 메모리 (./CLAUDE.md) — 프로젝트 루트에 두고 팀원과 공유하는 핵심 지침입니다. Git에 커밋하므로 팀 전체가 동일한 컨텍스트를 갖게 됩니다.

프로젝트 규칙 (.claude/rules/*.md) — 프로젝트별 규칙을 모듈 단위로 관리합니다. 경로별 조건부 로딩을 지원하며, 아래 “모듈식 규칙” 섹션에서 자세히 다룹니다.

프로젝트 로컬 (./CLAUDE.local.md) — 프로젝트에 속하지만 본인만 사용하는 설정입니다. 생성 시 자동으로 .gitignore에 추가됩니다. “내 로컬 API 키 경로는 여기”, “나는 이 디렉토리에서만 작업한다” 같은 개인 맥락을 적습니다.

📝 CLAUDE.md 작성하기

CLAUDE.md는 Memory 시스템의 핵심입니다. 잘 작성된 CLAUDE.md 하나가 세션마다 반복되는 설명 10번을 대체합니다.

기본 구조

# 프로젝트 개요

Astro 5 기반 블로그 프로젝트입니다.

## 명령어

- `pnpm dev` — 개발 서버 시작
- `pnpm build` — 프로덕션 빌드
- `pnpm test` — Vitest 테스트 실행

## 코딩 컨벤션

- TypeScript strict 모드 사용
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- 커밋 메시지: Conventional Commits (한글 본문)

## 아키텍처

- `src/components/` — 재사용 컴포넌트
- `src/utils/` — 유틸리티 함수
- `src/data/blog/` — 블로그 포스트 (Markdown)

효과적인 CLAUDE.md를 위한 원칙

구체적으로 작성하세요. 모호한 지침은 효과가 없습니다.

# ❌ 모호한 지침

코드를 적절히 포맷합니다.

# ✅ 구체적인 지침

- 들여쓰기: 2칸 스페이스 (탭 금지)
- 세미콜론: 사용하지 않음
- 따옴표: 작은따옴표 우선

자주 쓰는 명령어를 포함하세요. Claude가 빌드, 테스트, 린트 명령어를 매번 package.json을 읽지 않아도 됩니다.

금지 사항도 명시하세요. “하지 마라”도 중요한 지침입니다.

## 금지 사항

- `any` 타입 사용 금지
- console.log 커밋 금지
- 직접 DOM 조작 금지 (React ref 사용)

파일 임포트 (@ 참조)

CLAUDE.md가 길어지면 다른 파일을 참조할 수 있습니다.

프로젝트 개요는 @README.md를 참조하세요.
npm 명령어는 @package.json을 확인하세요.

# 추가 지침

- git 워크플로우: @docs/git-instructions.md
- 개인 설정: @~/.claude/my-instructions.md

상대 경로와 절대 경로 모두 지원하며, 재귀적 임포트도 가능합니다 (최대 5홉). 처음 임포트할 때 승인 대화가 나타나고, 이후에는 자동으로 로드됩니다.

💡 팁: 마크다운 코드 블록(`) 안의 @ 참조는 평가되지 않으므로, 예시 코드에서 안전하게 @파일명을 언급할 수 있습니다.

🤖 자동 메모리 (Auto Memory)

자동 메모리는 Claude가 작업하면서 스스로 학습한 내용을 기록하는 기능입니다. 2026년 2월에 공식 추가되었으며, 기본적으로 활성화되어 있습니다.

어떤 것을 기록하나?

• 프로젝트의 빌드/테스트 명령어와 규칙
• 여러 세션에서 확인된 코딩 패턴과 컨벤션
• 디버깅 과정에서 발견한 인사이트와 해결책
• 아키텍처 결정 사항과 주요 파일 경로
• 사용자의 워크플로우 선호도

파일 구조

~/.claude/projects/<project>/memory/
├── MEMORY.md           # 간결한 인덱스 (200줄 제한, 매 세션 로드)
├── debugging.md        # 디버깅 관련 상세 노트
├── api-conventions.md  # API 설계 결정사항
└── patterns.md         # 코드 패턴 메모

MEMORY.md 는 자동 메모리의 목차 역할입니다. 처음 200줄만 매 세션 시작 시 자동 로드되므로, 핵심 정보를 간결하게 유지하는 것이 중요합니다. 200줄을 초과하면 주제별 파일로 분산하고 MEMORY.md에서 링크합니다.

주제별 파일은 세션 시작 시 로드되지 않습니다. Claude가 관련 작업을 할 때 필요에 따라 읽습니다.

실제 자동 메모리 예시

이 블로그 프로젝트의 자동 메모리를 예로 보겠습니다.

# Blog Project Memory

## OG Image Build OOM Issue

See [og-image-oom.md](./og-image-oom.md) for detailed analysis.

**Status**: Resolved. `@resvg/resvg-js` → `sharp` 교체.
16개 OG 이미지 ~70ms/개 정상 생성.

이전 세션에서 OG 이미지 빌드 OOM 문제를 해결한 경험이 자동으로 기록되어 있습니다. 다음 세션에서 비슷한 문제가 생기면 Claude가 이 기록을 참조하여 더 빠르게 대응할 수 있습니다.

자동 메모리 제어하기

필요에 따라 자동 메모리를 끄거나 켤 수 있습니다.

# 설정 파일을 통한 제어
# ~/.claude/settings.json (전역)
{ "autoMemoryEnabled": false }

# .claude/settings.json (프로젝트)
{ "autoMemoryEnabled": false }

# 환경 변수로 제어 (최우선 적용)
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1  # 강제 비활성화
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0  # 강제 활성화

Claude에게 직접 요청하여 메모리를 관리할 수도 있습니다.

"pnpm이 아니라 bun을 사용한다는 것을 기억해줘"
"이전에 기록한 OG 이미지 관련 메모리를 업데이트해줘"
"더 이상 styled-components를 안 쓰니까 관련 메모리를 삭제해줘"

📁 모듈식 규칙 (.claude/rules/)

프로젝트 지침이 많아지면 하나의 CLAUDE.md에 모든 것을 넣기 어렵습니다. .claude/rules/ 디렉토리를 사용하면 주제별로 규칙을 분리할 수 있습니다.

기본 사용법

.claude/rules/
├── code-style.md       # 코드 스타일 규칙
├── testing.md          # 테스트 작성 규칙
├── frontend/
│   └── react.md        # React 컴포넌트 규칙
└── backend/
    └── api.md          # API 엔드포인트 규칙

하위 디렉토리까지 재귀적으로 탐색하므로, 도메인별로 자유롭게 구조화할 수 있습니다.

경로별 규칙 (Path-scoped Rules)

YAML 프론트매터로 특정 파일에만 적용되는 규칙을 정의할 수 있습니다. 해당 경로의 파일을 작업할 때만 로드되므로, 불필요한 컨텍스트 로딩을 줄여줍니다.

---
paths:
  - "src/api/**/*.ts"
  - "src/middleware/**/*.ts"
---

# API 개발 규칙

- 모든 엔드포인트는 입력 검증을 포함할 것
- 에러 응답은 RFC 7807 형식을 따를 것
- 인증이 필요한 엔드포인트는 미들웨어로 처리할 것

지원하는 glob 패턴은 다양합니다.

💡 팁: ~/.claude/rules/에 사용자 수준 규칙을 둘 수도 있습니다. 모든 프로젝트에 적용하고 싶은 개인 코딩 규칙이 있다면 여기에 작성하세요.

💡 실전 활용 팁

1. /init으로 빠르게 시작하기

새 프로젝트에서 CLAUDE.md를 처음부터 작성할 필요 없습니다. /init 명령을 실행하면 Claude가 프로젝트를 분석하여 CLAUDE.md 초안을 자동 생성합니다.

> /init

생성된 초안을 검토하고 프로젝트에 맞게 수정하면 됩니다.

2. /memory로 메모리 직접 편집하기

/memory 명령으로 시스템 에디터에서 메모리 파일을 직접 열고 편집할 수 있습니다. 자동 메모리가 잘못된 정보를 기록했거나, 수동으로 정보를 추가하고 싶을 때 유용합니다.

3. CLAUDE.md를 팀과 공유하기

프로젝트 루트의 CLAUDE.md는 Git에 커밋하세요. 팀원 모두가 동일한 Claude Code 컨텍스트를 갖게 됩니다.

개인 설정은 CLAUDE.local.md에 분리합니다. 자동으로 .gitignore에 추가되므로 팀 리포지토리를 오염시키지 않습니다.

4. 자동 메모리의 MEMORY.md는 200줄 이내로

MEMORY.md는 매 세션 시작 시 로드됩니다. 200줄을 초과하면 잘리므로, 핵심 정보만 간결하게 유지하세요. 상세 내용은 주제별 파일로 분산하고 MEMORY.md에서 링크합니다.

# Project Memory

## 빌드 이슈

See [build-issues.md](./build-issues.md) for details.

## 코딩 패턴

See [patterns.md](./patterns.md) for details.

5. 계층 구조를 전략적으로 활용하기

마무리

Claude Code Memory의 핵심을 세 가지로 요약합니다.

1. CLAUDE.md는 팀의 공유 매뉴얼: 프로젝트 규칙, 명령어, 컨벤션을 한 곳에 정리하고 Git으로 공유하세요. 구체적일수록 효과적입니다.
2. 자동 메모리는 Claude의 경험 노트: 세션을 거듭할수록 Claude가 프로젝트를 더 잘 이해합니다. MEMORY.md를 200줄 이내로 유지하고, 정기적으로 검토하세요.
3. 계층 구조를 활용하세요: 글로벌 설정, 프로젝트 공유 지침, 개인 로컬 설정, 경로별 규칙을 적절히 분리하면 각 맥락에 꼭 필요한 정보만 로드됩니다.

/init으로 CLAUDE.md를 생성하는 것부터 시작해 보세요. 두세 번의 세션만 거치면 “또 설명해야 하나”라는 생각이 사라질 것입니다.

참고 자료

공식 문서

• Memory 문서 (한국어) ↗
• Memory 문서 (영문) ↗

관련 포스트

• Claude Code Agent Teams 완벽 가이드 — Agent Teams에서의 CLAUDE.md 활용
• Claude Code Remote Control — 원격 세션에서의 프로젝트 설정 유지