CLAUDE.md

CLAUDE.md는 Claude Code가 세션 시작 때 컨텍스트로 읽는 마크다운 지침 파일입니다. 프로젝트·개인·조직 단위의 지속 지침을 담습니다. 세션마다 새 컨텍스트 윈도우로 시작하는 Claude Code에 빌드 명령, 코딩 규칙, 프로젝트 구조처럼 매번 다시 설명할 내용을 적어 두는 자리입니다. 내용은 사용자 메시지 형태의 맥락으로 전달되므로 도구 실행을 막는 권한 설정처럼 강제되지는 않습니다.

파일 위치와 불러오는 순서

Claude Code 메모리 문서에 따르면 CLAUDE.md는 범위에 따라 네 곳에 둡니다. IT 부서가 배포하는 조직 관리 정책 파일, 모든 프로젝트에 적용되는 사용자 파일 ~/.claude/CLAUDE.md, 팀이 버전 관리로 공유하는 프로젝트 파일 ./CLAUDE.md 또는 ./.claude/CLAUDE.md, .gitignore에 넣고 혼자 쓰는 ./CLAUDE.local.md입니다. 불러오는 순서는 넓은 범위에서 좁은 범위로 가므로 프로젝트 지침이 사용자 지침보다 뒤에 놓입니다.

Claude Code는 작업 디렉터리와 그 위의 모든 디렉터리에서 CLAUDE.md와 CLAUDE.local.md를 찾아 시작할 때 불러옵니다. foo/bar/에서 실행하면 foo/CLAUDE.md가 foo/bar/CLAUDE.md보다 먼저 컨텍스트에 들어가고, 파일들은 서로 덮어쓰지 않고 이어 붙습니다. 작업 디렉터리 아래 하위 디렉터리의 CLAUDE.md는 시작할 때 읽지 않고, Claude가 그 하위 디렉터리의 다른 파일을 읽거나 쓰거나 편집할 때 불러옵니다.

파일 안에서 @path/to/import 구문으로 다른 파일을 가져올 수 있으며, 가져온 파일도 시작할 때 함께 불러오고 재귀 가져오기는 최대 네 단계까지입니다. 같은 문서는 파일 하나를 200줄 안쪽으로 유지하도록 권합니다. 특정 파일에만 필요한 지침은 paths 필드를 둔 .claude/rules/ 규칙으로 옮기면 일치하는 파일을 다룰 때만 불러옵니다.

AGENTS.md·자동 메모리와의 관계

저장소에 AGENTS.md가 있어도 작업 디렉터리나 그 위에 프로젝트 CLAUDE.md(.claude/CLAUDE.md 포함)나 CLAUDE.local.md가 있으면, Claude Code 메모리 문서가 설명하는 기본 설정에서는 CLAUDE.md만 읽습니다. 그런 파일이 하나도 없을 때 Claude Code는 AGENTS.md를 프로젝트 지침으로 읽고, CLAUDE.md가 @AGENTS.md로 가져오면 AGENTS.md도 그 안에 포함됩니다. /config의 Project instructions를 claude-md-and-agents-md로 바꾸면 두 파일을 함께 읽습니다. 2026년 10월 11일(UTC) 확인한 문서 기준으로 AGENTS.md를 직접 읽으려면 Claude Code v2.1.277 이상이 필요합니다.

자동 메모리(auto memory)는 사람이 쓰는 CLAUDE.md와 달리 Claude가 사용자의 수정과 선호를 바탕으로 직접 남기는 메모이며, 로컬 세션에서는 기본으로 켜져 있습니다. 메모는 ~/.claude/projects/<project>/memory/에 저장되고, 같은 git 저장소의 작업 트리와 하위 디렉터리가 이 디렉터리 하나를 공유하며 다른 기기와는 공유되지 않습니다. 색인 파일 MEMORY.md는 처음 200줄 또는 25KB 중 먼저 닿는 쪽까지만 세션 시작 때 불러오고, 이 한도는 CLAUDE.md에는 적용되지 않습니다.

CLAUDE.md에는 빌드 명령, 규칙, 프로젝트 구성처럼 모든 세션에서 유지할 사실을 두고, 여러 단계로 된 절차나 코드베이스 일부에만 해당하는 내용은 스킬이나 경로 범위 규칙으로 옮기도록 안내돼 있습니다. 스킬은 사용자가 호출하거나 Claude가 요청과 관련 있다고 판단할 때만 불러오므로 항상 컨텍스트를 차지하지 않습니다.

지침 파일과 강제 설정의 경계

CLAUDE.md 내용은 시스템 프롬프트 뒤에 사용자 메시지로 전달되고, Claude Code 메모리 문서는 모호하거나 서로 충돌하는 지침일수록 엄격하게 지켜진다는 보장이 없다고 설명합니다. 두 지침이 어긋나면 Claude가 그중 하나를 임의로 고를 수 있습니다. 문서는 "코드를 보기 좋게 정리"보다 "들여쓰기는 공백 2칸"처럼 확인할 수 있는 지침이 더 잘 지켜진다고 예를 듭니다.

Claude Code 권한 설정 문서는 권한 규칙을 모델이 아닌 Claude Code가 집행하며, 프롬프트나 CLAUDE.md의 지침은 Claude가 시도하는 행동에 영향을 줄 뿐 허용 범위를 바꾸지 않는다고 적었습니다. 이 규칙은 deny, ask, allow 순서로 평가됩니다. Claude Code 설정 문서에 따르면 권한 같은 설정은 ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json과 조직의 관리 설정에 JSON 키로 저장됩니다.

조직 단위 배포에서도 관리 설정과 관리 CLAUDE.md의 역할이 나뉩니다. 특정 도구나 명령을 막는 일은 관리 설정의 permissions.deny가 맡고, 코드 스타일과 규정 준수 안내는 관리 CLAUDE.md에 둡니다. 커밋 직전처럼 정해진 시점에 반드시 실행할 동작은 Claude의 판단과 상관없이 정해진 동작을 실행하는 훅(hook)으로 작성하도록 메모리 문서는 권합니다.