Claude Code 메모리 시스템 완전 가이드: 자동 메모리 vs CLAUDE.md

Q: CLAUDE.md는 어디에 두어야 하나요?

프로젝트별 CLAUDE.md는 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 둡니다. 전역 CLAUDE.md(모든 프로젝트 공통 설정)는 ~/.claude/CLAUDE.md에 둡니다. 세 위치 모두 사용하면 Claude가 자동으로 병합합니다.

Q: 세션 메모리는 얼마나 오래 유지되나요?

Claude Code 세션이 활성 상태인 동안만 유지됩니다. /exit 입력 또는 터미널 종료 시 사라집니다. 영속이 필요하면 CLAUDE.md에 옮기세요.

Claude Code는 두 가지 메모리 계층을 사용합니다 — 세션 종료 시 사라지는 200K 토큰 세션 메모리, 그리고 매 세션 시작 시 자동 로드되는 영속적인 CLAUDE.md 파일입니다 (2026 기준). 둘의 차이를 이해해야 프로젝트 컨텍스트가 세션 간에 살아남는지, 아니면 터미널을 닫는 순간 사라지는지 결정할 수 있습니다. 실전 CLAUDE.md 패턴은 CLAUDE.md 효과적 작성법에서 더 자세히 다룹니다.

두 가지 메모리 종류

1. 세션 메모리 (휘발성)

Claude가 한 세션 동안 학습한 모든 것 — 코드베이스 구조, 사용자가 언급한 코딩 선호도, 디버깅 컨텍스트 — 은 활성 컨텍스트 윈도우에 살아 있습니다. /exit을 입력하거나 터미널을 닫으면 그 메모리는 사라집니다. 다음 세션은 백지 상태로 시작합니다.

세션 메모리 크기는 200K 토큰(약 한국어 11만 자, 영어 단어 15만 개 분량). 이 한도를 넘으면 Claude는 이전 메시지를 압축하거나 잘라내기 시작해 응답 품질이 떨어집니다.

2. CLAUDE.md 파일 (영속)

CLAUDE.md는 프로젝트 루트(또는 ~/.claude/CLAUDE.md 전역 파일)에 두는 마크다운 파일입니다. Claude Code가 시작할 때마다 자동으로 읽어 시스템 프롬프트에 주입합니다. 즉, 매 세션마다 똑같은 컨텍스트를 다시 설명하지 않아도 됩니다.

# 프로젝트별 CLAUDE.md
./CLAUDE.md           # 이 프로젝트에서만 적용
./.claude/CLAUDE.md   # 동일한 효과
~/.claude/CLAUDE.md   # 모든 프로젝트에 전역 적용

세 위치를 모두 사용하면 Claude는 셋 다 읽고 병합합니다. 일반적으로 우선순위는: 프로젝트 > 전역.

CLAUDE.md에 무엇을 넣어야 하는가

좋은 사용 예 (영속할 만한 정보)

프로젝트 구조 요약 — "이 레포는 Next.js 15 + Prisma + Postgres 모노레포. apps/web, apps/api, packages/db 구성"
명령 규칙 — "테스트는 bun test로, 배포는 vercel --prod로 실행"
불변 규칙 — "절대 prisma migrate reset를 운영 DB에 실행하지 말 것"
외부 시스템 정보 — "Stripe 시크릿 키는 .env.local에 있음. 코드에 하드코딩 금지"
도메인 지식 — "여기서 'plan'은 GrowthBook feature flag, 결제 플랜이 아님"

나쁜 사용 예 (CLAUDE.md에 넣지 말 것)

시크릿 — API 키, 토큰, 비밀번호 (.env로 분리)
자주 바뀌는 정보 — 어제 작성 중이던 작업 상세 (휘발성 메모리에 둘 것)
거대한 코드 덤프 — Claude는 필요한 파일을 직접 읽음. 미리 붙여넣지 말 것
5천 토큰 이상의 장문 — 매 세션 비용 증가. 핵심 30-40줄로 압축

토큰 비용 계산

CLAUDE.md 1,000 토큰 = 매 세션 시작 시 약 $0.001 (Sonnet 4.6 기준). 하루 30 세션이면 월 $0.90. 합리적 수준입니다.

하지만 CLAUDE.md가 10,000 토큰을 넘어가면:

세션 시작 비용: 월 $9
프롬프트 캐싱 적용 시 80-90% 절감 가능 (반복되는 시스템 프롬프트이기 때문)

자세한 비용 최적화는 Claude API 비용 완전 가이드를 참고하세요.

실전 CLAUDE.md 예시

예시 1: Next.js SaaS 프로젝트

# Project: ChartFly SaaS

## 스택
- Next.js 15 App Router + TypeScript
- Prisma + Postgres (Neon)
- TailwindCSS + shadcn/ui
- Stripe + Loops.so

## 명령어
- `bun dev` — 로컬 개발 서버
- `bun test` — 테스트 (Vitest)
- `bun run build` — 빌드 (배포 전 필수)
- `vercel --prod --yes` — 운영 배포

## 코드 규칙
- 컴포넌트는 src/components에, 라우트는 src/app에
- API 라우트는 항상 Zod로 입력 검증
- DB 접근은 src/lib/db.ts의 prisma 인스턴스만 사용
- 절대 prisma db push를 운영 DB에 실행하지 말 것

## 도메인 어휘
- "plan" = GrowthBook feature flag (결제 플랜 X)
- "credits" = Stripe metered billing 사용량
- "chart" = ECharts 그래프 컴포넌트

이 정도가 약 250 토큰. 매 세션 시작 시 부담 없는 크기입니다.

예시 2: 모노레포 — 패키지별 CLAUDE.md

대형 모노레포는 패키지마다 CLAUDE.md를 두는 것이 효과적입니다. Claude Code는 작업 디렉토리의 CLAUDE.md를 우선 로드하므로, cd packages/ui && claude 실행 시 UI 패키지 컨텍스트만 로드됩니다. 더 자세한 패턴은 Claude Code 모노레포 가이드에서 확인할 수 있습니다.

자동 메모리 vs CLAUDE.md 결정 트리

질문: 이 정보를 다음 세션에서도 자동으로 알기 원하는가?

│
├── 예 → CLAUDE.md에 추가
│     └── 단, 5천 토큰 이상이면 압축 또는 분할
│
└── 아니오 → 세션 내에서만 사용
      └── 다음 세션은 다시 설명 필요

좋은 휴리스틱: "이 정보가 일주일 후에도 유효할까?" 예라면 CLAUDE.md. 아니라면 세션 메모리.

CLAUDE.md 자동 생성

claude init 명령으로 프로젝트 분석 후 CLAUDE.md 초안을 자동 생성할 수 있습니다.

cd my-project
claude init  # 프로젝트 구조 스캔 → CLAUDE.md 작성

생성된 CLAUDE.md는 항상 검토 후 다듬어야 합니다. Claude의 자동 분석은 종종 너무 장황하거나 자명한 내용을 포함합니다. 30-50줄로 압축이 목표입니다.

흔한 실수 5가지

1. CLAUDE.md에 시크릿 저장

API 키, 비밀번호는 절대 CLAUDE.md에 넣지 마세요. CLAUDE.md는 git에 커밋되는 경우가 많고, 매 세션 컨텍스트로 노출됩니다. .env.local에 저장하고 CLAUDE.md에는 "API 키는 .env.local에 있음" 정도만 명시합니다.

2. 5천 토큰 넘는 장문 작성

CLAUDE.md가 너무 길면 (1) 비용 증가, (2) Claude가 중요한 부분을 놓침, (3) 매 세션 시작 시 5-10초 추가 지연. 30-50줄 기준으로 압축하세요.

3. 자주 바뀌는 정보 포함

"오늘 작업 중인 기능", "어제 본 버그" 같은 정보는 휘발성 세션 메모리에 둡니다. CLAUDE.md는 일주일 이상 유지될 정보만.

4. CLAUDE.md를 .gitignore에 추가

CLAUDE.md는 팀과 공유해야 할 프로젝트 컨텍스트입니다. .gitignore에 넣지 말고 커밋하세요. 시크릿이 들어가지 않도록 검토만 철저히.

5. 매 세션 시작 시 같은 컨텍스트 반복 입력

"이 프로젝트는 Next.js 모노레포로..." 같은 설명을 매번 타이핑하고 있다면 → CLAUDE.md에 옮기세요. 그게 CLAUDE.md의 존재 이유입니다.

메모리 압축 (auto-compact)

세션 메모리가 200K 토큰 한도에 가까워지면 Claude Code는 자동으로 이전 메시지를 압축합니다. 압축된 메시지는 핵심 요약만 남고 원문은 사라집니다. 압축이 일어나면 화면에 알림이 표시됩니다.

압축이 자주 발생한다면:

한 세션 안에서 너무 많은 작업을 하고 있다는 신호
/exit 후 새 세션 시작 권장
CLAUDE.md에 영속할 만한 정보가 있는지 점검

Frequently Asked Questions

CLAUDE.md는 어디에 두어야 하나요?

프로젝트별 CLAUDE.md는 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 둡니다. 전역 CLAUDE.md(모든 프로젝트 공통 설정)는 ~/.claude/CLAUDE.md에 둡니다. 세 위치 모두 사용하면 Claude가 자동으로 병합합니다.

CLAUDE.md를 git에 커밋해도 되나요?

네, 권장합니다. CLAUDE.md는 팀이 공유할 프로젝트 컨텍스트입니다. 단, 시크릿/API 키가 들어가지 않도록 검토하세요. 시크릿은 .env.local에 두고 .gitignore에 추가합니다.

세션 메모리는 얼마나 오래 유지되나요?

Claude Code 세션이 활성 상태인 동안만 유지됩니다. /exit 입력 또는 터미널 종료 시 사라집니다. 영속이 필요하면 CLAUDE.md에 옮기세요.

CLAUDE.md가 너무 크면 어떻게 되나요?

5천 토큰 이상이 되면 (1) 매 세션 시작 시 비용 증가 ($0.005 정도), (2) Claude가 중요 부분을 놓칠 수 있음, (3) 초기 응답 지연 발생. 30-50줄로 압축이 목표입니다.

여러 CLAUDE.md 파일이 충돌하면 어떻게 되나요?

Claude는 모든 CLAUDE.md를 읽고 병합합니다. 같은 주제에 대해 다른 지시가 있으면 보통 더 가까운 위치(프로젝트 > 전역)가 우선합니다. 명시적 충돌은 피하는 것이 좋습니다.

Claude Code 메모리 최적화 마스터하기

P1 Power Prompts 300 ($29) — Claude Code 메모리 활용, CLAUDE.md 작성 패턴, 세션 관리 전략을 포함한 300개의 검증된 프롬프트 컬렉션. 솔로 개발자 기준 월 평균 50시간 절약.