# 메모리와 컨텍스트 (CLAUDE.md)

> Claude Code가 CLAUDE.md 메모리 파일을 어떻게 발견하고, 로드하고, 우선순위를 결정하는지 설명합니다.

Claude Code는 일반 마크다운 파일 기반의 계층적 메모리 시스템을 지원합니다. 파일 시스템의 여러 레벨에 있는 `CLAUDE.md` 파일에 지시사항을 작성해서 Claude의 동작을 전역적으로, 프로젝트별로, 또는 사용자별로 커스터마이징할 수 있습니다.

## 4단계 메모리 계층

메모리 파일은 다음 순서로 로드됩니다(낮은 우선순위 → 높은 우선순위). **나중에** 로드된 파일이 우선합니다. 컨텍스트 윈도우에서 나중에 나타나는 지시사항에 모델이 더 주의를 기울이기 때문입니다.

**1단계: Managed 메모리 (최저 우선순위)**
- 경로: `/etc/claude-code/CLAUDE.md`
- 관리자 또는 배포 도구가 설정한 시스템 전체 지시사항. 머신의 모든 사용자에게 적용됩니다.

**2단계: User 메모리**
- 경로: `~/.claude/CLAUDE.md` 및 `~/.claude/rules/*.md`
- 모든 프로젝트에 적용되는 개인 전역 지시사항. 선호하는 코드 스타일, 기본 언어, git 사용자명 등 개인 설정에 적합합니다. 이 파일은 어떤 저장소에도 커밋되지 않습니다.

**3단계: Project 메모리**
- 경로(CWD까지 각 상위 디렉토리에서 확인): `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`
- 팀 전체가 공유하는 코드베이스에 커밋된 지시사항. 프로젝트 컨벤션, 아키텍처 노트, 테스트 커맨드에 이상적입니다.

**4단계: Local 메모리 (최고 우선순위)**
- 경로: `CLAUDE.local.md` (각 상위 디렉토리에서 확인)
- `.gitignore`에 추가해야 하는 개인 프로젝트별 재정의. 로컬 환경 경로, 개인 디버깅 노트 등에 사용합니다.

> 📝 현재 작업 디렉토리에 더 가까운 파일이 **나중에** 로드되어 **더 높은 우선순위**를 가집니다. 프로젝트 루트의 `CLAUDE.md`가 상위 디렉토리의 것보다 우선합니다.

## 파일 발견 알고리즘

Claude Code 시작 시, 현재 작업 디렉토리에서 **파일시스템 루트까지** 올라가며 각 레벨의 메모리 파일을 수집합니다. 발견 순서는 낮은 우선순위 파일이 먼저 조립된 컨텍스트에 나타나도록 보장합니다:

1. Managed 파일이 먼저 로드됩니다
2. User 파일이 다음으로 로드됩니다
3. Project 및 Local 파일은 **루트에서 CWD로 내려가며** 반복됩니다 — 상위 디렉토리가 하위 디렉토리보다 먼저 옵니다

> 📝 발견된 파일 목록은 대화 기간 동안 메모이제이션됩니다. `/memory`를 실행해 메모리 에디터를 열고 강제 리로드하거나, 세션을 재시작해 Claude Code 외부에서 만들어진 변경 사항을 반영합니다.

## `@include` 지시어

메모리 파일은 `@` 표기법으로 다른 파일을 참조할 수 있습니다. 참조된 파일은 포함하는 파일 이전에 별도 항목으로 컨텍스트에 삽입됩니다.

```markdown
# My project CLAUDE.md

@./docs/architecture.md
@./docs/conventions/typescript.md

커밋 전에 항상 `bun test`를 실행하세요.
```

| 구문 | 해석 |
|------|------|
| `@filename` | 포함하는 파일 디렉토리 기준 상대 경로 |
| `@./relative/path` | 명시적 상대 경로 |
| `@~/home/path` | 사용자 홈 디렉토리 기준 경로 |
| `@/absolute/path` | 절대 경로 |

**규칙:**
- 코드 블록 및 인라인 코드 안의 `@include`는 무시됩니다
- 순환 참조는 감지되어 건너뜁니다
- 존재하지 않는 파일은 조용히 무시됩니다
- 최대 include 깊이는 **5단계**입니다
- 텍스트 기반 파일 형식만 포함됩니다(`.md`, `.ts`, `.py`, `.json` 등). 이미지와 PDF 같은 바이너리 파일은 건너뜁니다

## `.claude/rules/*.md` — 세분화된 규칙 파일

모든 것을 하나의 큰 `CLAUDE.md`에 넣는 대신, `.claude/rules/` 안의 여러 마크다운 파일로 지시사항을 나눌 수 있습니다:

```
my-project/
├── CLAUDE.md
└── .claude/
    └── rules/
        ├── testing.md
        ├── typescript-style.md
        └── git-workflow.md
```

모든 `.md` 파일은 자동으로 로드됩니다. 규칙 파일은 **경로 범위 프론트매터**도 지원합니다:

```markdown
---
paths:
  - "src/api/**"
  - "src/services/**"
---

항상 의존성 주입을 사용하세요. 구체적인 구현을 직접 import하지 마세요.
```

`paths`가 설정되면, 규칙 파일은 Claude가 해당 glob 패턴과 일치하는 파일을 작업할 때만 컨텍스트에 주입됩니다. 대규모 프로젝트에서 컨텍스트를 간결하게 유지합니다.

## 최대 파일 크기

단일 메모리 파일의 권장 최대 크기는 **40,000자**입니다. 이 한계를 초과하는 파일은 플래그 처리되고, Claude가 전체 내용을 읽지 못할 수 있습니다. 메모리 파일은 집중적이고 간결하게 유지하세요.

## 메모리가 Claude 동작에 미치는 영향

메모리 파일이 로드되면, 다음과 같은 프리픽스가 붙은 단일 컨텍스트 블록으로 조립됩니다:

> *"Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written."*

즉, CLAUDE.md 파일의 지시사항이 Claude의 내장 기본값보다 우선합니다. 이를 활용해 프로젝트 컨벤션을 강제하거나, 특정 작업을 제한하거나, 도메인 지식을 주입할 수 있습니다.

## 각 레벨 사용 지침

| 레벨 | 용도 |
|------|------|
| **Managed 메모리** | 모든 사용자가 따라야 하는 조직 전체 정책, 보안 가이드라인 |
| **User 메모리** (`~/.claude/CLAUDE.md`) | 모든 프로젝트에 걸쳐 적용되는 개인 선호도: 응답 언어, 커밋 메시지 스타일 |
| **Project 메모리** (`CLAUDE.md`) | 팀과 공유하는 프로젝트 컨벤션: 테스트 실행 방법, 빌드 커맨드, 아키텍처 결정 |
| **Local 메모리** (`CLAUDE.local.md`) | 특정 프로젝트의 개인 재정의: 로컬 환경 경로, 개인 디버깅 노트 |

## `/memory` 커맨드

Claude Code REPL 안에서 `/memory`를 실행해 메모리 파일 에디터를 엽니다. 현재 로드된 메모리 파일을 보여주고, 직접 편집하며, 저장 시 컨텍스트를 리로드합니다.

> 💡 Claude에게 직접 물어볼 수도 있습니다: *"CLAUDE.md에 항상 2칸 들여쓰기를 사용한다는 규칙을 추가해줘."* Claude가 적절한 메모리 파일을 찾아 지시사항을 작성합니다.

## 메모리 로딩 비활성화

| 방법 | 효과 |
|------|------|
| `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1` | 모든 메모리 파일 로딩 완전 비활성화 |
| `--bare` 플래그 | CWD 워크에서 메모리 파일 자동 발견 건너뜀 |
| `claudeMdExcludes` 설정 | 건너뛸 메모리 파일 경로의 Glob 패턴 |
