요약
Claude Code는 매 세션마다 컨텍스트 윈도우가 초기화된다. CLAUDE.md와 Auto Memory는 이 초기화를 극복하고 지식을 세션 간에 유지하는 두 가지 메커니즘이다. 단, CLAUDE.md는 강제 설정이 아닌 컨텍스트로 취급되므로 진짜 강제력은 Hooks에서 나온다.
개념 정리
메모리의 두 종류
| CLAUDE.md | Auto Memory | |
|---|---|---|
| 작성자 | 내가 직접 씀 | Claude가 자동으로 씀 |
| 내용 | 팀 규칙, 아키텍처, 코딩 컨벤션 | Claude가 학습한 내 패턴과 선호도 |
| 위치 | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | ~/.claude/projects/.../MEMORY.md |
두 파일 모두 매 대화 시작 시 로드된다. Claude는 이를 강제 설정이 아닌 컨텍스트로 취급한다.
파일 계층 구조 — 3종 비교
~/.claude/CLAUDE.md # 전역: 나 × 모든 프로젝트
./CLAUDE.md # 프로젝트: 팀 × 이 프로젝트 (git 커밋됨)
./CLAUDE.local.md # 로컬: 나 × 이 프로젝트 (git 제외)각각 어디에 무엇을 쓸지 기준:
~/.claude/CLAUDE.md→ 나라는 사람의 전역 습관과 선호도- 예: "나는 항상 console.log 대신 logger를 쓴다"
./CLAUDE.md→ 이 프로젝트의 팀 공통 규칙- 예: "함수명은 camelCase를 쓴다"
./CLAUDE.local.md→ 내 로컬 환경의 특수 사항- 예: "내 로컬 Redis 포트는 6380이다"
로딩 방식
루트의 CLAUDE.md는 세션 시작 시 항상 통째로 로드된다. 하위 디렉토리의 CLAUDE.md는 Claude가 그 폴더 작업을 할 때만 로드된다.
CLAUDE.md 생성 시 '선(先) 파일 구축, 후(後) 초기화' 전략이 효과적임.
- 맥락 파악: AI가 기존 파일(Sub-agent, Hooks)을 스캔하여 프로젝트 특성에 맞는 맞춤형 지침을 자동 생성.
- 정확도 향상: 빌드 명령어, 테스트 스크립트 등 기술적 세부 사항이 실제 파일 구조와 일치하게 작성됨.
- 효율성: 범용적인 내용이 아닌, 프로젝트 고유의 워크플로우가 즉시 반영되어 수정 시간이 단축됨.
추천 워크플로우 (4단계)
1)구조 설계: Sub-agent 설정, Custom Hooks, 스크립트 파일 등 핵심 인프라를 먼저 생성.
2)동작 확인: 작성한 스크립트나 도구가 정상 작동하는지 체크.
3)초기화: claudecode init (또는 ./init) 실행하여 CLAUDE.md 생성.
4)미세 조정: 생성된 문서에 하위 에이전트 호출 규칙이나 필수 준수 사항을 수동으로 보완.
잘 쓰는 법
파일당 200줄 이하를 유지한다. 더 길어지면 Claude의 지시 준수율이 떨어진다.
# 나쁜 예 (모호함)
- 코드를 깔끔하게 유지해줘
# 좋은 예 (구체적이고 검증 가능)
- 들여쓰기는 2칸 공백 사용
- 커밋 전 반드시 npm test 실행@ 임포트로 파일 분리
# 아키텍처
@docs/architecture.md
# 테스트 가이드
@docs/testing-guidelines.mdClaude가 테스트 관련 작업을 할 때만 testing-guidelines.md를 불러온다.
대화 중 빠른 메모리 추가
#을 앞에 붙이면 Claude가 즉시 CLAUDE.md에 추가한다.
# 이 프로젝트에서는 항상 async/await를 쓰고 .then() 체이닝은 쓰지 마CLAUDE.md의 한계
CLAUDE.md → "npm test 실행해줘" (가이드라인)
Hooks (Module 06) → 커밋 전 npm test 자동 실행, 실패 시 exit 2로 차단 (집행)CLAUDE.md는 가이드라인, Hooks는 집행자.
핵심 요약 (TL;DR)
- 매 세션 컨텍스트 초기화 → CLAUDE.md + Auto Memory로 극복
- 파일 3종:
./CLAUDE.md(팀),./CLAUDE.local.md(나 × 이 프로젝트),~/.claude/CLAUDE.md(나 × 전체) - 200줄 이하, 구체적으로 작성할수록 Claude가 잘 따른다
@파일명으로 큰 내용은 분리해서 토큰 효율을 높인다- 강제력이 없다 — 진짜 강제는 Hooks(Module 06)에서 나온다
다음에 알아볼 것
- Module 06: Hooks — CLAUDE.md 규칙을 실제로 강제하는 방법
.claude/rules/디렉토리로 규칙을 주제별로 분리하는 패턴- Auto Memory가 학습하는 내용을 직접 확인하고 편집하는 방법
[Series] Claude Code Fundamentals - Memory (CLAUDE.md)
Summary
Claude Code resets its context window at the start of every session. CLAUDE.md and Auto Memory are the two mechanisms that overcome this reset and carry knowledge across sessions. However, CLAUDE.md is treated as context, not enforced configuration — real enforcement comes from Hooks.
Key Concepts
Two Types of Memory
| CLAUDE.md | Auto Memory | |
|---|---|---|
| Author | You write it manually | Claude writes it automatically |
| Content | Team rules, architecture, coding conventions | Patterns and preferences Claude learns from you |
| Location | ./CLAUDE.md or ./.claude/CLAUDE.md | ~/.claude/projects/.../MEMORY.md |
Both files are loaded at the start of every conversation. Claude treats them as context, not enforced configuration.
File Hierarchy — 3 Types Compared
~/.claude/CLAUDE.md # Global: you × all projects
./CLAUDE.md # Project: team × this project (git-committed)
./CLAUDE.local.md # Local: you × this project (git-excluded)What goes where:
~/.claude/CLAUDE.md→ Your personal habits and preferences across all projects- e.g. "I always use logger instead of console.log"
./CLAUDE.md→ Team-wide rules for this project- e.g. "Use camelCase for function names"
./CLAUDE.local.md→ Your local environment specifics- e.g. "My local Redis port is 6380"
Loading Behavior
The root CLAUDE.md is always loaded in full at session start. CLAUDE.md files in subdirectories load on demand only when Claude works in those directories.
Writing Effective Instructions
Keep each file under 200 lines. Beyond that, Claude's adherence to instructions degrades.
# Bad (too vague)
- Keep the code clean
# Good (specific and verifiable)
- Use 2-space indentation
- Always run npm test before committingSplitting Files with @ Imports
# Architecture
@docs/architecture.md
# Testing Guide
@docs/testing-guidelines.mdClaude only loads testing-guidelines.md when working on test-related tasks, keeping base context efficient.
Quick Memory Addition During Chat
Prefix any instruction with # and Claude adds it to CLAUDE.md immediately.
# Always use async/await in this project, never .then() chainingThe Limit of CLAUDE.md
CLAUDE.md → "Please run npm test" (guideline)
Hooks (Module 06) → Automatically runs npm test before commit, blocks with exit 2 if it fails (enforcement)CLAUDE.md is the guideline. Hooks is the enforcer.
TL;DR
- Context resets every session → overcome with CLAUDE.md + Auto Memory
- Three file types:
./CLAUDE.md(team),./CLAUDE.local.md(you × this project),~/.claude/CLAUDE.md(you × all projects) - Keep under 200 lines and write specific instructions for better adherence
- Use
@filenameimports to split large content and save tokens - No enforcement power — real enforcement comes from Hooks (Module 06)
