CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 마크다운 지시 파일입니다. 빌드 명령, 코딩 규칙, 프로젝트 구조처럼 매번 다시 설명하기 번거로운 내용을 한 번 적어 두면, Claude가 모든 대화에서 그 맥락을 갖고 시작합니다. 이 글은 Anthropic 공식 문서를 토대로 CLAUDE.md를 어디에 두고, 어떻게 쓰고, 어떻게 관리하는지 정리합니다.
CLAUDE.md란 무엇인가
Claude Code는 세션마다 빈 컨텍스트로 시작합니다. CLAUDE.md는 그 빈 컨텍스트에 "이 프로젝트에서 늘 지켜야 할 것"을 채워 주는 파일입니다. 평문 마크다운으로 작성하면 Claude가 세션 시작 시 읽어 들입니다. 공식 문서는 CLAUDE.md를 "다시 설명하게 될 내용을 적어 두는 곳"으로 설명합니다.
한 가지 분명히 할 점은, CLAUDE.md가 강제 설정이 아니라 맥락(컨텍스트)으로 전달된다는 것입니다. Claude가 읽고 따르려 하지만 100% 강제되지는 않습니다. 반드시 차단되거나 실행돼야 하는 규칙은 훅(hook)이나 관리 설정으로 처리하는 것이 정확합니다.
두 가지 메모리: CLAUDE.md와 자동 메모리
Claude Code의 메모리는 두 축으로 나뉘며, 둘 다 매 세션 시작 시 로드됩니다.
- CLAUDE.md — 사용자가 직접 쓰는 지시·규칙. 코딩 표준, 워크플로, 프로젝트 구조 등.
- 자동 메모리(Auto memory) — Claude가 작업 중 스스로 적는 학습·패턴(빌드 명령, 디버깅 인사이트, 선호 등). 기본 켜짐이며 Claude Code v2.1.59 이상에서 동작합니다.
요약하면, 내가 통제하고 싶은 규칙은 CLAUDE.md에, Claude가 알아서 쌓는 경험은 자동 메모리에 담깁니다.
어디에 두나: 4가지 위치
CLAUDE.md는 범위에 따라 여러 위치에 둘 수 있고, 넓은 범위부터 좁은 범위 순으로 로드됩니다(위 그림). 모든 파일은 덮어쓰기가 아니라 이어 붙여(concatenate) 컨텍스트에 들어갑니다.
- 관리자 정책 — 조직 전체. macOS
/Library/Application Support/ClaudeCode/CLAUDE.md, Linux·WSL/etc/claude-code/CLAUDE.md, WindowsC:\Program Files\ClaudeCode\CLAUDE.md. 개인 설정으로는 제외할 수 없습니다. - 사용자 —
~/.claude/CLAUDE.md. 내 모든 프로젝트에 적용되는 개인 취향. - 프로젝트 —
./CLAUDE.md또는./.claude/CLAUDE.md. 팀이 git으로 공유합니다. - 로컬 —
./CLAUDE.local.md. 나만 쓰는 프로젝트별 설정으로,.gitignore에 추가합니다.
Claude Code는 작업 디렉터리에서 상위로 올라가며 각 폴더의 CLAUDE.md를 찾고, 루트에서 작업 폴더 방향으로 이어 붙입니다. 하위 폴더의 CLAUDE.md는 그 폴더의 파일을 읽을 때 필요에 따라 로드됩니다.
가장 빠른 시작: /init
빈손으로 시작한다면 Claude Code에서 /init을 실행하세요. Claude가 코드베이스를 분석해 빌드 명령·테스트 방법·프로젝트 관례를 담은 CLAUDE.md 초안을 만들어 줍니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선안을 제안합니다.
잘 쓰는 법
CLAUDE.md는 길이에 상관없이 전부 컨텍스트에 로드되므로(자동 메모리와 다릅니다), 토큰을 아끼고 준수율을 높이려면 다음을 지키세요.
- 분량: 파일당 200줄 이내를 권장합니다. 길수록 컨텍스트를 더 먹고 준수율이 떨어집니다.
- 구체성: 검증 가능할 만큼 구체적으로 씁니다. "포맷 잘 해줘"보다 "들여쓰기는 스페이스 2칸"이 낫습니다.
- 구조: 마크다운 헤더·불릿으로 관련 지시를 묶습니다.
- 일관성: 서로 모순되는 규칙이 있으면 Claude가 임의로 하나를 고를 수 있으니 주기적으로 정리하세요.
다른 파일 가져오기: @import
CLAUDE.md는 @경로 문법으로 다른 파일을 불러올 수 있습니다. 상대·절대 경로 모두 가능하고, 가져온 파일이 또 다른 파일을 가져오는 재귀는 최대 4단계까지 허용됩니다.
See @README for project overview and @package.json for available npm commands. # Additional Instructions - git workflow @docs/git-instructions.md
여러 git 워크트리에서 개인 지시를 공유하려면, 홈 디렉터리 파일을 가져오는 방식(@~/.claude/my-project-instructions.md)이 편리합니다.
규칙 분리: .claude/rules/
프로젝트가 커지면 지시를 .claude/rules/ 아래 주제별 파일로 나눌 수 있습니다. 각 파일 상단에 paths: 프런트매터로 글롭 패턴을 지정하면, 해당 패턴의 파일을 다룰 때만 그 규칙이 로드되어 컨텍스트를 아낄 수 있습니다.
AGENTS.md를 쓰던 프로젝트라면
Claude Code는 AGENTS.md가 아니라 CLAUDE.md를 읽습니다. 이미 AGENTS.md가 있다면 CLAUDE.md에서 @AGENTS.md로 가져오면 두 도구가 같은 지시를 공유합니다. 그 아래에 Claude 전용 지시를 덧붙일 수도 있습니다.
자동 메모리 잠깐 보기
자동 메모리는 Claude가 작업하며 스스로 쌓는 노트로, 저장소별 ~/.claude/projects/<project>/memory/에 마크다운으로 보관됩니다. 색인 파일 MEMORY.md의 앞부분(처음 200줄 또는 25KB 중 먼저 도달하는 한도)만 매 세션 로드되고, 세부 노트는 필요할 때 읽힙니다. /memory 명령으로 로드된 파일을 보고 켜고 끌 수 있습니다.
Claude가 CLAUDE.md를 안 따를 때
CLAUDE.md는 시스템 프롬프트가 아니라 그 뒤의 사용자 메시지로 전달되므로 엄격한 강제는 아닙니다. 잘 안 지켜진다면 ① /memory로 실제 로드 여부 확인, ② 지시를 더 구체적으로, ③ 파일 간 모순 제거를 점검하세요. 커밋 직전처럼 특정 시점에 반드시 실행돼야 하는 일은 훅(hook)으로 작성하는 것이 확실합니다.
함께 보면 좋은 글 · 출처
바로 쓸 수 있는 예시는 CLAUDE.md 템플릿 모음에서 확인하세요. 이 글의 사실관계는 Anthropic 공식 Claude Code 문서를 따랐습니다 — code.claude.com/docs/en/memory. 세부 동작은 버전에 따라 달라질 수 있습니다.