CLAUDE.md 메모리 시스템

Claude Code는 CLAUDE.md 파일을 통해 지속적인 컨텍스트를 유지합니다. 매 대화마다 같은 규칙을 반복 설명할 필요 없이, 파일에 한 번 작성해두면 Claude가 자동으로 읽고 따릅니다. 이 시스템은 4계층 계층 구조로 설계되어 전역 설정부터 개인 설정까지 세밀하게 제어할 수 있습니다.

4계층 메모리 계층 구조

레벨	위치	범위	용도
Level 1 Managed Memory	`/etc/claude-code/CLAUDE.md`	시스템 전체	관리자 설정, 재정의 불가
Level 2 User Memory	`~/.claude/CLAUDE.md`, `~/.claude/rules/*.md`	개인 전역	개인 코드 스타일, 언어 설정
Level 3 Project Memory	`CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`	프로젝트 전체	팀 공유 규칙, VCS 커밋
Level 4 Local Memory	`CLAUDE.local.md`	개인 프로젝트별	개인 프로젝트별 재정의

Level 1: Managed Memory

/etc/claude-code/CLAUDE.md

시스템 관리자가 설정하는 최상위 계층입니다. 기업 환경에서 보안 정책, 금지 작업 목록, 표준 도구 사용 규칙을 강제할 때 사용합니다. 이 파일의 내용은 다른 계층에서 재정의할 수 없습니다.

# 회사 보안 정책
- 프로덕션 데이터베이스 직접 접근 금지
- 비밀번호를 코드에 하드코딩하지 말 것
- 모든 외부 API 호출은 팀 리뷰 필요

Level 2: User Memory

~/.claude/CLAUDE.md
~/.claude/rules/*.md

개인 전역 설정입니다. 모든 프로젝트에서 공통으로 적용되는 개인 선호도를 설정합니다.

# 내 코딩 설정
- 언어: 한국어로 응답
- 들여쓰기: 2칸 스페이스
- Git 커밋 형식: conventional commits
- 항상 타입 안전성 확인

~/.claude/rules/ 디렉토리의 파일들은 주제별로 분리할 수 있습니다.

~/.claude/rules/
  git-workflow.md
  coding-style.md
  testing.md

Level 3: Project Memory

CLAUDE.md                  (프로젝트 루트)
.claude/CLAUDE.md
.claude/rules/*.md

팀이 공유하는 프로젝트별 규칙입니다. VCS(Git)에 커밋하여 팀 전체에 배포합니다.

# 프로젝트 규칙

## 아키텍처
- 모든 API는 /src/api/ 디렉토리에 위치
- 데이터베이스 쿼리는 repository 패턴 사용

## 테스트
- 모든 새 기능에 단위 테스트 필수
- E2E 테스트는 Playwright 사용

## 배포
- main 브랜치는 항상 배포 가능 상태 유지

Level 4: Local Memory

CLAUDE.local.md

개인적인 프로젝트별 재정의입니다. 팀 설정을 유지하면서 개인 워크플로우를 추가합니다. .gitignore에 추가하여 팀과 공유되지 않게 합니다.

# 개인 설정 (공유하지 않음)
- 내 개발 서버: http://localhost:3001
- 테스트 DB: postgresql://localhost/myapp_dev
- 스테이징 배포 전 항상 내 포크에 먼저 푸시

# .gitignore에 추가
echo "CLAUDE.local.md" >> .gitignore

파일 탐색 알고리즘

Claude Code는 세션 시작 시 CLAUDE.md 파일을 다음 순서로 탐색합니다.

1. 현재 작업 디렉토리(CWD)에서 시작
2. 파일시스템 루트(/)를 향해 상향 탐색
3. 각 디렉토리에서 CLAUDE.md, .claude/CLAUDE.md 확인
4. 발견된 모든 파일을 수집

로딩 순서: 하위 파일이 먼저 로드됩니다.

/                     ← 마지막 로드
├── etc/claude-code/CLAUDE.md
└── home/user/
    ├── .claude/CLAUDE.md
    └── projects/myapp/
        ├── CLAUDE.md         ← 먼저 로드 (더 구체적)
        └── .claude/CLAUDE.md

하위 파일이 먼저 로드되므로 더 구체적인 규칙이 상위 규칙보다 우선 적용됩니다. 단, Level 1(Managed Memory)은 항상 최우선입니다.

최대 권장 크기

CLAUDE.md 파일의 최대 권장 크기는 40,000자 입니다. 이 한도를 초과하면 컨텍스트 윈도우를 과도하게 소비하고 응답 품질이 저하될 수 있습니다.

효율적인 작성 팁:

중복 제거: 여러 파일에 같은 내용 반복 금지
핵심만 유지: Claude가 이미 아는 일반적인 내용 제외
분리 저장: rules/*.md로 주제별 분리하여 가독성 향상
@include 활용: 큰 문서를 여러 파일로 분리 후 참조

계층별 작성 가이드

실제로 어떤 내용을 어느 계층에 작성해야 할지 판단 기준입니다.

Q: 모든 프로젝트에 적용되는 내용인가?
→ Yes: User Memory (~/.claude/CLAUDE.md)

Q: 팀과 공유해야 하는 내용인가?
→ Yes: Project Memory (CLAUDE.md 커밋)

Q: 개인적인 프로젝트별 설정인가?
→ Yes: Local Memory (CLAUDE.local.md, gitignore)

Q: 회사 전체에 강제해야 하는 정책인가?
→ Yes: Managed Memory (/etc/claude-code/CLAUDE.md)