클로드 코드 CLAUDE.md, 어디에 두고 어떻게 작동하는지 한 번에 정리

한눈에 보는 핵심

CLAUDE.md(클로드 코드 설정 파일)는 매 세션 시작 때 자동으로 로드되는 지침 파일이에요. 파일 위치는 전역·프로젝트·하위 디렉토리 세 단계로 나뉘고, 더 구체적인 위치일수록 우선순위가 높아요. /memory 명령어를 쓰면 클로드가 세션 중에 배운 내용을 다음 세션까지 저장해두는 자동 메모리 폴더를 직접 확인하고 편집할 수 있어요.

CLAUDE.md가 뭐고 왜 자동으로 로드되나요

CLAUDE.md는 클로드 코드(Claude Code)가 세션을 시작할 때 자동으로 읽어 들이는 마크다운 지침 파일이에요. 파일 내용은 시스템 프롬프트처럼 동작해서, "항상 TypeScript strict 모드를 써요" 같은 규칙을 한 번 써두면 매번 새 세션을 열어도 클로드가 그 규칙을 기억한 채로 시작해요.

클로드 코드는 기본적으로 각 세션을 새 컨텍스트 윈도우로 시작하기 때문에, 이전 대화 내용을 자동으로 기억하지 못해요. CLAUDE.md는 바로 이 한계를 보완하는 공식 메커니즘이에요. 파일을 직접 작성하거나, 클로드 코드 안에서 /init 명령어를 실행하면 현재 프로젝트 구조를 분석해 초안을 자동 생성해줘요. 생성된 초안은 참고용 시작점이에요. 불필요한 내용은 과감히 지우고 핵심 규칙만 남기는 게 좋은데, 파일이 200줄을 넘으면 컨텍스트를 많이 차지해서 실제 지침 준수율이 떨어질 수 있어요.

파일 위치와 범위 — 어디에 놓느냐에 따라 적용 범위가 달라져요

CLAUDE.md는 한 곳에만 놓는 게 아니라 여러 위치에 동시에 존재할 수 있어요. 각 위치마다 적용 범위가 다르고, 더 구체적인(하위) 위치의 파일이 상위 파일보다 우선 적용돼요.

위치별로 정리하면 아래와 같아요.
1) 전역(사용자) 범위: ~/.claude/CLAUDE.md — 모든 프로젝트에 공통 적용되는 개인 설정. 코드 스타일 선호도나 자주 쓰는 단축 지침을 여기에 두면 돼요.
2) 프로젝트 범위: ./CLAUDE.md 또는 ./.claude/CLAUDE.md — 해당 프로젝트에서 작업하는 모든 사람에게 적용돼요. 빌드 명령, 아키텍처 결정, 코딩 컨벤션을 여기에 써두면 팀 전체가 동일한 기준으로 작업할 수 있어요. Git에 커밋해서 팀과 공유하는 게 일반적이에요.
3) 하위 디렉토리 범위: path/to/dir/CLAUDE.md — 클로드가 해당 디렉토리 안의 파일을 다룰 때 필요에 따라 로드해요. 모노레포(monorepo)처럼 폴더별로 기술 스택이 다를 때 유용해요.
4) 개인 로컬 설정: CLAUDE.local.md — Git에 올리고 싶지 않은 개인 설정을 여기에 써요. 자동으로 .gitignore 처리돼요.

파일 이름은 대소문자를 구분해요. 반드시 CLAUDE.md(대문자 CLAUDE, 소문자 .md) 형식으로 작성해야 해요. claude.md나 Claude.md로 저장하면 클로드 코드가 파일을 찾지 못해요.

파일 로드 순서 — 세션이 시작되면 어떤 순서로 읽나요

클로드 코드는 세션을 시작할 때 여러 CLAUDE.md 파일을 아래 순서로 로드해요. 나중에 로드된 파일이 앞서 로드된 파일보다 우선 적용돼요.

1) 관리 정책(macOS: /Library/Application Support/ClaudeCode/CLAUDE.md, Linux: /etc/claude-code/CLAUDE.md) — 조직 관리자가 배포하는 정책으로, 다른 어떤 설정도 이걸 덮어쓸 수 없어요.
2) 전역 사용자 설정 (~/.claude/CLAUDE.md)
3) 현재 작업 디렉토리 위 상위 경로들의 CLAUDE.md — 세션 시작 위치부터 루트(/)까지 거슬러 올라가며 찾은 파일을 전부 로드해요.
4) 현재 작업 디렉토리의 CLAUDE.md 또는 ./.claude/CLAUDE.md
5) 하위 디렉토리 CLAUDE.md — 세션 시작 시 전부 로드되는 게 아니라, 클로드가 실제로 해당 폴더 파일을 다룰 때 필요에 따라(on demand) 로드돼요.

.claude/rules/ 폴더를 활용하면 지침을 주제별로 나눌 수 있어요. code-style.md, testing.md 등 파일로 쪼개두면 하나의 CLAUDE.md가 비대해지는 걸 막을 수 있고, 팀원별로 담당 파일만 수정하면 돼요. rules/ 파일에는 paths 프론트매터로 특정 경로에만 적용되도록 범위를 지정하는 것도 가능해요.

@path/to/file.md 구문으로 다른 파일을 임포트(import)하는 방법도 있어요. CLAUDE.md 본문을 간결하게 유지하면서 상세 내용은 별도 파일로 분리할 수 있고, 재귀 참조도 지원돼요.

/memory 명령어와 자동 메모리 — 클로드가 스스로 기록하는 노트예요

클로드 코드에는 CLAUDE.md 외에 자동 메모리(Auto Memory)라는 두 번째 시스템이 있어요. 사용자가 직접 작성하는 CLAUDE.md와 달리, 자동 메모리는 클로드가 세션 중에 스스로 학습한 내용을 기록해요. 빌드 명령, 디버깅 패턴, 코드 스타일 선호도 등이 자동으로 저장돼요.

자동 메모리는 ~/.claude/projects/<프로젝트명>/memory/ 폴더 아래에 마크다운 파일로 저장돼요. MEMORY.md가 인덱스 파일로 매 세션 시작 시 로드되고, debugging.md·api-conventions.md 같은 주제별 파일이 함께 생성될 수 있어요. 클로드가 매 세션마다 무언가를 저장하는 건 아니고, 향후 대화에 유용하다고 판단하는 정보만 선별해서 기록해요.

/memory 명령어를 실행하면 저장된 자동 메모리 폴더를 기본 편집기로 열어줘요. 내용이 틀렸거나 오래됐다면 직접 수정하거나 삭제할 수 있어요. 일반 마크다운 파일이라 어떤 텍스트 편집기로도 편집 가능해요. 자동 메모리를 비활성화하려면 settings.json에 autoMemoryEnabled: false를 설정하거나, 환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 지정하면 돼요(버전에 따라 옵션명이 다를 수 있어요).

세션 중에 클로드에게 빠르게 메모를 남기고 싶을 때는 # 기호로 시작하는 입력을 사용해요. "#항상 pnpm을 써요" 처럼 입력하면 클로드가 해당 내용을 CLAUDE.md 또는 자동 메모리에 추가할지 물어봐요.

CLAUDE.md가 안 먹을 때 — 대표 원인과 확인 루틴

설정을 분명히 써뒀는데 클로드가 무시하는 것처럼 느껴질 때, 아래 순서로 확인해보면 대부분 원인을 찾을 수 있어요.

1) 파일 이름 오타: claude.md나 Claude.md로 저장했는지 확인해요. 정확히 CLAUDE.md(전부 대문자, 확장자 소문자)여야 해요.
2) 파일 위치 범위 확인: 클로드 코드를 실행하는 디렉토리와 파일 위치가 맞는지 확인해요. 서브 디렉토리의 CLAUDE.md는 해당 폴더 파일을 다룰 때만 로드돼요.
3) 충돌하는 지침: 두 개 이상의 CLAUDE.md 파일이 같은 항목에 대해 다른 지침을 담고 있으면 클로드가 하나를 임의로 선택할 수 있어요. 전체 파일을 훑어 충돌을 제거해요.
4) 파일이 너무 길 때: 200줄을 초과하면 컨텍스트 소비가 늘어나고 지침 준수율이 낮아져요. 불필요한 내용을 정리하거나 .claude/rules/로 분리해요.
5) 자동 메모리 확인: /memory를 실행해서 자동 메모리 폴더를 열고, 의도와 다른 내용이 저장돼 있지 않은지 확인해요.

인스트럭션이 언제, 어떤 파일에서 로드됐는지 정확히 추적하고 싶다면 InstructionsLoaded 훅(hook)을 활용하는 방법도 있어요. 경로별 규칙이나 하위 디렉토리 지연 로드를 디버깅할 때 유용해요.

CLAUDE.md 위치와 로드 순서를 이해하면, 설정이 왜 안 먹는지 원인을 빠르게 좁힐 수 있고 팀과 효율적으로 규칙을 공유할 수 있어요.

---

같은 문제로 고민하셨다면 공감 버튼 눌러주세요.
비슷한 설정 관련 정보가 필요하실 때 구독하기 해두면 좋아요.
다시 찾아보기 쉽게 저장해두면 편해요.

출처
확인일: 2026-03-31
Claude Code 공식 문서 — 메모리(한국어)
Claude Code 공식 문서 — Settings
Claude Code 200% 활용하기 — 메모리, 스킬, 훅