CLAUDE.md 완벽 가이드: Claude Code 프로젝트 메모리 파일 작성법

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, Windows C:\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 예시 모음에서 확인하세요. Claude Code를 VS Code·JetBrains에서 쓰는 법은 IDE 연동 가이드에서 다룹니다.

바로 쓸 수 있는 예시는 CLAUDE.md 템플릿 모음에서 확인하세요. 이 글의 사실관계는 Anthropic 공식 Claude Code 문서를 따랐습니다 — code.claude.com/docs/en/memory. 세부 동작은 버전에 따라 달라질 수 있습니다.

처음이라면: 처음 만드는 CLAUDE.md (입문)

프로젝트가 커져서 CLAUDE.md를 여러 폴더에 나눠 두고 싶다면 CLAUDE.md 폴더별 배치와 우선순위 정리 글이 도움이 됩니다. 루트·서브디렉터리·홈 디렉터리 파일이 어떤 순서로 적용되는지 설명합니다.

관련 글

• CLAUDE.md 파일을 여러 폴더에 나눠 배치하는 방법: 루트·서브디렉터리·홈 디렉터리 우선순위 완전 정리
• CLAUDE.md 실전 예제 모음: 웹앱·모노레포·규칙·안티패턴 복붙 템플릿
• 처음 만드는 CLAUDE.md — 한 줄부터 시작하는 입문
• Claude Opus 4.7 완벽 가이드: 새 기능과 사양 총정리
• Claude Code 설치 가이드: native vs npm, Windows까지