Claude가 프로젝트를 기억하는 방법

Claude Code의 모든 세션은 빈 컨텍스트로 시작하지만, 두 가지 메커니즘이 세션 간 지식을 이어줍니다. 하나는 CLAUDE.md 파일로, 사용자가 직접 써서 Claude에게 영속 컨텍스트를 주는 것이고, 다른 하나는 **auto memory(자동 메모리)**로, 사용자의 수정·선호를 바탕으로 Claude가 스스로 메모를 쌓는 것입니다. 이 문서는 CLAUDE.md 작성·구성, .claude/rules/로 규칙을 파일 유형별로 범위 지정하는 법, auto memory 설정, 그리고 지침이 지켜지지 않을 때의 문제 해결까지 다룹니다.

출처: 공식문서

본문

CLAUDE.md vs auto memory

두 메모리 시스템은 상호 보완적입니다. 둘 다 모든 대화 시작 시 로드되며, Claude는 이를 강제 구성이 아닌 컨텍스트로 취급합니다. 결정과 무관하게 행동을 아예 차단하고 싶다면 PreToolUse 훅을 쓰세요.

	CLAUDE.md 파일	Auto memory
누가 쓰나	사용자	Claude
내용	지침·규칙	학습·패턴
범위	프로젝트·사용자·조직	저장소별(워크트리 간 공유)
로드	모든 세션	모든 세션 (첫 200줄 또는 25KB)
용도	코딩 표준·워크플로우·아키텍처	선호·수정사항·코드에서 유추 못 하는 컨텍스트

CLAUDE.md 파일

CLAUDE.md는 프로젝트·개인 워크플로우·조직 전반에 대한 영속 지침을 담은 마크다운 파일입니다. 평문으로 작성하고 Claude는 매 세션 시작 시 읽습니다.

언제 추가하나? Claude가 같은 실수를 두 번째 할 때, 코드 리뷰가 Claude가 알았어야 할 것을 잡아냈을 때, 지난 세션에서 똑같이 친 수정·설명을 다시 칠 때, 새 동료가 같은 컨텍스트가 필요할 때.

위치는 스코프에 따라 다릅니다 (로드 순서 = 넓은 범위 → 구체):

스코프	위치	용도
관리형 정책	macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` / Linux·WSL: `/etc/claude-code/CLAUDE.md` / Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`	IT/DevOps가 관리하는 조직 전역 지침
사용자	`~/.claude/CLAUDE.md`	모든 프로젝트의 개인 선호
프로젝트	`./CLAUDE.md` 또는 `./.claude/CLAUDE.md`	팀 공유 프로젝트 지침
로컬	`./CLAUDE.local.md`	개인 프로젝트 전용; `.gitignore`에 추가

작업 디렉토리 위의 상위 디렉토리 CLAUDE.md는 시작 시 로드되고, 하위 디렉토리의 파일은 Claude가 그 디렉토리 파일을 읽을 때 로드됩니다.

효과적인 지침 작성: 파일당 200줄 미만을 목표로 하세요(더 길면 컨텍스트를 먹고 준수가 떨어짐). 마크다운 헤더·불릿으로 구조화하고, 구체적으로 검증 가능하게 쓰세요(예: "2-스페이스 들여쓰기" 대신 "코드 포맷 잘 하기"). 예: "커밋 전에 npm test 실행", "API 핸들러는 src/api/handlers/에 위치". /init으로 시작 CLAUDE.md를 자동 생성할 수 있습니다.

파일 가져오기(@import): @path/to/import 문법으로 추가 파일을 가져올 수 있습니다. 상대/절대 경로 모두 허용하며, 가져온 파일은 상대 경로를 자신이 있는 파일 기준으로 해석하고 최대 4단계까지 재귀 가져오기가 가능합니다. 백틱으로 감싸면(`@README`) 가져오지 않고 리터럴로 남습니다. 개인 전용이라면 CLAUDE.local.md를 만들어 .gitignore에 넣으세요.

AGENTS.md: Claude Code는 CLAUDE.md를 읽지 AGENTS.md는 읽지 않습니다. 이미 AGENTS.md를 쓴다면 @AGENTS.md로 가져오는 CLAUDE.md를 만들거나 ln -s AGENTS.md CLAUDE.md 심링크를 쓰세요(Windows는 관리자 권한 필요, @AGENTS.md 가져오기 권장).

로드 방식: 현재 디렉토리와 모든 상위 디렉토리의 CLAUDE.md·CLAUDE.local.md가 연결(concatenate)되어 파일시스템 루트부터 작업 디렉토리 순으로 정렬됩니다. 시작 위치에 가까운 지침이 나중에 읽히고, 각 디렉토리에서 CLAUDE.local.md는 CLAUDE.md 뒤에 붙습니다. 블록 HTML 주석()은 컨텍스트 주입 전에 제거됩니다(컨텍스트 토큰 절약용). 추가 디렉토리에서 로드하려면 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config처럼 설정하세요.

`.claude/rules/`로 규칙 정리하기

큰 프로젝트는 .claude/rules/ 디렉토리로 지침을 여러 파일로 나눌 수 있습니다. 파일 하나당 한 주제(예: testing.md, api-design.md)이며 재귀적으로 발견되므로 하위 디렉토리로도 구성할 수 있습니다. paths가 없는 규칙은 시작 시 .claude/CLAUDE.md와 같은 우선순위로 로드됩니다.

경로별 규칙(path-specific rules): YAML 프론트매터의 paths 필드로 특정 파일에만 적용할 수 있습니다:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- 모든 API 엔드포인트는 입력 검증을 포함해야 한다
- 표준 오류 응답 형식을 사용한다

패턴 예: **/*.ts(모든 TS 파일), src/**/*(src 아래 전체), *.md(루트 마크다운), 매칭은 Claude가 해당 파일을 읽을 때 트리거됩니다. 중괄호 확장(src/**/*.{ts,tsx})도 지원하며, 규칙별로 확장 패턴 1,000개·4MiB 예산을 공유합니다. 규칙은 심링크로 여러 프로젝트에 공유할 수 있고, ~/.claude/rules/에 두면 전 기계에 적용됩니다(프로젝트 규칙보다 먼저 로드).

대규모 팀의 CLAUDE.md 관리

조직 전역 CLAUDE.md는 관리 정책 위치에 배포하며 개인 설정으로 못 뺍니다. managed-settings.json의 claudeMd 키로 별도 파일 없이 내용을 넣을 수도 있습니다. 대형 모노레포에서는 claudeMdExcludes 설정으로 특정 파일을 제외할 수 있습니다(절대 경로 glob 매칭, 레이어 간 배열 병합). 기술적 강제는 managed settings로, 행동 지침은 CLAUDE.md로: 도구·명령 차단은 permissions.deny, 샌드박스는 sandbox.enabled, 코드 스타일·데이터 처리·행동 지침은 관리 CLAUDE.md.

Auto memory

사용자가 아무것도 쓰지 않아도 Claude가 세션 간 지식을 쌓습니다. 네 종류의 메모리를 프론트매터의 type 필드로 기록합니다: user(역할·전문성·선호), feedback(수정·확인된 접근법), project(진행 중 작업·마감·결정), reference(프로젝트 외 정보의 위치). 코드베이스에서 유추 가능한 것(아키텍처·파일 경로·디버그 수정)이나 CLAUDE.md에 이미 있는 것은 건너뜁니다.

기본 켜져 있습니다. /memory의 토글 또는 autoMemoryEnabled 설정으로 제어하며, 환경변수로는 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1입니다. 저장 위치는 ~/.claude/projects/<project>/memory/이고, 저장소당 하나(워크트리·하위 디렉토리 공유). MEMORY.md 인덱스 + 주제별 파일(user_role.md, feedback_testing.md)로 구성됩니다.

작동 방식: 매 대화 시작 시 MEMORY.md의 첫 200줄 또는 처음 25KB 중 먼저 도달하는 쪽이 로드됩니다(초과분은 미로드). 한도를 넘으면 Claude에 줄이도록 알립니다. CLAUDE.md는 최대 4MiB까지 전체 로드됩니다. 주제 파일은 시작 시 로드되지 않고 필요할 때 표준 파일 도구로 읽힙니다. 메모리 파일이 YAML 프론트매터로 시작하면 modified 필드에 ISO 8601 타임스탬프가 기록됩니다(v2.1.214+).

`/memory`로 보기·편집

/memory 명령은 사용자·프로젝트 스코프의 CLAUDE.md, CLAUDE.local.md 및 기타 메모리 파일 위치를 나열하고 auto memory 토글·폴더 열기 옵션을 제공합니다. GUI 에디터면 별도 창에서 열리고, 터미널 에디터는 퇴장할 때까지 터미널을 차지합니다. "항상 pnpm을 쓰고 npm은 쓰지 마", "API 테스트는 로컬 Redis가 필요해" 같은 요청은 auto memory로 저장되고, "이걸 CLAUDE.md에 추가해"라면 지침 파일에 추가됩니다.

메모리 문제 해결

CLAUDE.md를 안 따를 때: /context의 Memory files 목록으로 로드 여부 확인, 위치·구체성·충돌 지침 점검. 특정 시점 강제 실행이 필요하면 훅으로, 시스템 프롬프트 수준이 필요하면 --append-system-prompt 사용.
auto memory에 뭐가 저장됐는지 모를 때: /memory로 auto memory 폴더를 열어 평문 마크다운을 읽기·편집·삭제.
CLAUDE.md가 너무 클 때: 200줄 초과 시 컨텍스트 낭비·준수 저하. 경로별 규칙으로 줄이거나 /doctor로 점검(코드에서 유추 가능한 내용 제안 삭제).
/compact 후 지침이 사라질 때: 프로젝트 루트 CLAUDE.md는 통합 후 재주입됩니다. 대화 전용 지침이라면 CLAUDE.md에 넣어야 지속됩니다.

Claude가 프로젝트를 기억하는 방법