Claude Code에는 「메모리 (memory)」 메커니즘이 여러 개 있습니다. 무엇을 어디에 적어야 할지 혼란스러울 수 있어 정리해 보았습니다.

크게 나누면 CLAUDE.md (지시 파일)와 auto memory (자동 메모리) 두 종류가 있으며, 각각 글로벌(Global) 및 프로젝트 단위가 있습니다.

스코프	경로	용도
글로벌	~/.claude/CLAUDE.md	모든 프로젝트 공통 지시
프로젝트	<project>/CLAUDE.md	프로젝트 고유 지시
서브 디렉토리	<project>/src/CLAUDE.md 등	디렉토리 단위 지시

수동으로 관리하는 설정 파일입니다. 코딩 규약(Coding Convention) · 커맨드 목록 · 아키텍처(Architecture) 설명 등을 적어두면, 대화할 때마다 자동으로 읽어옵니다.

# 프로젝트 개요
## 자주 사용하는 커맨드
```bash
pnpm build # 빌드
pnpm test # 테스트
pnpm lint # Lint

커밋 규약

feat / fix / docs / chore의 Conventional Commits 형식

| 스코프 | 경로 |
|---|---|
| 글로벌 | `~/.claude/memory/` |
| 프로젝트 | `~/.claude/projects/<project-path>/memory/` |

Claude가 대화 속에서 배운 것을 자동으로 기록하는 메커니즘입니다. `MEMORY.md` (인덱스 파일)와 개별 Markdown 파일로 구성됩니다.

auto memory에는 4가지 종류가 있습니다.

| 종류 | 내용 |
|---|---|
| user | 사용자의 역할 · 스킬 · 선호도 |
| feedback | "이렇게 해줘", "그건 하지 마" 등의 지적 |
| project | 진행 중인 작업 · 방침 · 마감 기한 |
| reference | 외부 시스템으로의 포인터 (Linear · Slack 등) |

파일 포맷:

---

name: terse-response
description: 응답은 간결하게. 끝에 요약을 쓰지 말 것
...

〇〇를 기억해 둬
Remember that ...

Claude가 적절한 메모리 파일에 기록해 줍니다.

메모리는 일반적인 Markdown 파일이므로 직접 작성할 수 있습니다.

인덱스 확인

cat ~/.claude/projects/<project-path>/memory/MEMORY.md

파일을 직접 생성 · 편집

...

`MEMORY.md`에도 엔트리(Entry)를 추가해야 합니다:

• 사용자의 역할 — Node.js 5년, React는 초보자

앞으로는 PR을 작게 나누어 제출한다는 규칙을
feedback 메모리에 저장해 둬

와 같이 종류를 지정할 수도 있습니다.

| 관점 | CLAUDE.md | auto memory |
|---|---|---|
| 내용의 성질 | 프로젝트의 정적인 사실 | 동적 · 개인적인 정보 |
| ... | ... |

다른 사람(팀 멤버)이 읽고 도움이 되는가?
→ Yes: CLAUDE.md
→ No (자신 전용): memory
...

**CLAUDE.md에 적어야 할 것**: 커맨드 목록 · 아키텍처 설명 · 코딩 규약

**memory에 적어야 할 것**: 자신의 선호도 · 작업 스타일에 대한 피드백 · 진행 중인 작업의 문맥

-
**CLAUDE.md** = "이 프로젝트를 모르는 Claude에게 설명하는 것" (안정적 · 공유 가능)
**auto memory** = "Claude가 나와의 작업 스타일을 학습한 내용" (개인적 · 동적)
-

"기억해 둬"라고 한마디 전달하는 것만으로 auto memory에 저장되므로, 의식하지 않는 사이에 계속 축적해 나가는 것이 실용적인 사용법입니다.