CLAUDE.md 배치 장소와 우선순위

초급 과정 4주차에서 2주차의 3줄 지침서가 "계층 구조"로 확장됩니다. 루트의 CLAUDE.md는 전체 공통 규칙, frontend/와 backend/의 CLAUDE.md는 그 폴더 전용 규칙. 폴더가 바뀌면 적용되는 문맥도 달라집니다. 이 글은 그 계층을 공식 문서 기준으로 정확히 정리합니다. 어디에 둘 수 있고, 어떤 순서로 읽히고, 겹치면 어떻게 되는지.

앞 글 「@참조로 다른 파일 불러오기」가 한 파일 안에서 분리하는 법이었다면, 이 글은 파일을 여러 위치에 나누는 법입니다. 다음 글 「.claude/rules/로 규칙 모듈화하기」로 이어집니다.

핵심 요약

• 배치 장소는 조직 정책, 사용자 홈(~/.claude/CLAUDE.md), 프로젝트(./CLAUDE.md 또는 ./.claude/CLAUDE.md), 로컬(./CLAUDE.local.md) 네 곳입니다.
• 넓은 범위부터 순서대로 전부 읽혀 이어 붙습니다. 덮어쓰기가 아니라 연결이므로 "이기는 파일"은 없습니다.
• 상위 폴더의 CLAUDE.md는 시작 시 전부 로드되고, 하위 폴더의 것은 그 폴더 파일을 읽을 때 로드됩니다.
• 팀 규칙은 CLAUDE.md에 커밋, 개인 값은 CLAUDE.local.md에 두고 .gitignore에 직접 추가합니다.
• 무엇이 읽혔는지와 토큰 비중은 /context의 Memory files 목록으로 보고, 파일 편집은 /memory로 엽니다.

네 곳의 배치 장소와 읽기 순서

Claude Code는 현재 작업 디렉터리에서 파일 시스템 루트 방향으로 올라가며 각 폴더의 CLAUDE.md와 CLAUDE.local.md를 찾습니다. ~/Developer/shop/backend/에서 켰다면 ~/Developer/CLAUDE.md, ~/Developer/shop/CLAUDE.md, ~/Developer/shop/backend/CLAUDE.md가 모두 실립니다. 순서는 루트에 가까운 것부터이고, 시작한 폴더에 가장 가까운 파일이 마지막에 읽힙니다. 각 폴더 안에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙습니다.

작업 디렉터리 아래의 하위 폴더는 다릅니다. 시작 시 읽지 않고 Claude가 그 폴더의 파일을 읽을 때 함께 로드됩니다. 4주차 교재의 frontend/CLAUDE.md가 정확히 이 방식으로 동작합니다. 프론트엔드 파일을 건드리기 전까지는 컨텍스트를 차지하지 않습니다.

우리 개발 루트 ~/Developer/CLAUDE.md에는 "레포 12개 공통, 개별 규칙은 각 레포 CLAUDE.md를 따른다"는 몇 줄만 두고, 레포마다 자기 CLAUDE.md를 갖습니다. 어느 레포에서 켜도 루트 규칙이 먼저, 레포 규칙이 나중에 실립니다.

실무에서 쓰는 세 가지 배치 패턴

1. 프로젝트 루트: 팀이 공유하는 설정

./CLAUDE.md를 git에 커밋합니다. 빌드·테스트 명령, 아키텍처 결정, 코드 규칙, 건드리면 안 되는 파일. 개인 취향은 넣지 않습니다. 클론한 사람 모두에게 같은 규칙이 적용되는 것이 목적이므로 "나는 vim을 쓴다" 같은 줄이 들어가면 팀원이 지웁니다.

2. 사용자 레벨: 모든 프로젝트에 적용되는 개인 설정

~/.claude/CLAUDE.md에는 프로젝트와 무관한 내 습관을 둡니다. 우리 팀원 대부분은 "모든 응답은 한국어, 존댓말", "확실하지 않은 수치는 추측하지 말고 공식 문서를 먼저 확인" 같은 줄을 여기 둡니다. 어느 레포를 열어도 따라옵니다.

3. CLAUDE.local.md: 이 프로젝트에서만 쓰는 개인 설정

프로젝트 루트의 ./CLAUDE.local.md는 CLAUDE.md와 같은 방식으로 읽히지만 커밋하지 않습니다. 내 로컬 포트, 테스트 계정 이름, 샌드박스 URL, 내 기기에서만 다른 경로가 들어갑니다. 자동으로 무시되지 않으므로 .gitignore에 직접 추가합니다. 환경 변수 CLAUDE_CODE_NEW_INIT=1을 켠 상태에서 /init의 개인 옵션을 고르면 이 추가를 대신해 줍니다.

echo "CLAUDE.local.md" >> .gitignore

같은 저장소를 여러 git worktree로 쓰면 gitignore된 CLAUDE.local.md는 만든 worktree에만 존재합니다. 모든 worktree에서 같은 개인 지침을 쓰려면 홈의 파일을 @참조로 가리킵니다.

# CLAUDE.local.md
@~/.claude/shop-local.md

팀 공유와 개인 설정을 어떻게 나누나

같은 프로젝트, 팀 규칙과 내 환경 분리

판단 기준은 하나입니다. 팀원이 이 줄을 보고 "왜 내 컴퓨터에 이게 적혀 있지?"라고 할 내용이면 local입니다.

여러 프로젝트에 같은 스타일 유지

언어, 존댓말, 보고 형식, 커밋 메시지 습관은 ~/.claude/CLAUDE.md에 한 번만 씁니다. 프로젝트마다 복사하면 나중에 한 곳만 고쳐지고 나머지는 옛날 규칙으로 남습니다. 프로젝트별 규칙과 충돌하지 않도록 사용자 파일에는 프로젝트가 결정할 사항(들여쓰기, 프레임워크)을 적지 않습니다.

지금 어떤 파일이 읽혔는지 확인하려면

로드 확인은 /context, 편집은 /memory

/context를 입력하면 Memory files 목록에 현재 세션에 로드된 CLAUDE.md, CLAUDE.local.md, .claude/rules/ 파일이 나열됩니다. "지침을 썼는데 안 지킨다"는 문제의 절반은 이 목록에 파일이 없는 경우입니다. 위치가 틀렸거나 다른 폴더에서 켠 것입니다. /memory는 이 파일들을 골라 편집기로 여는 진입점이며, 자동 메모리를 켜고 끄는 토글도 여기 있습니다.

/context: 각 파일이 쓰는 토큰 수

/context는 컨텍스트 사용량을 항목별로 보여 줍니다. CLAUDE.md 항목이 전체의 큰 몫을 차지하면 분리 대상입니다. 우리 팀은 월 1회 이 화면을 보고 200줄을 넘은 파일을 rules나 Skill로 뺍니다. 더 정확히 추적하려면 InstructionsLoaded 훅으로 어떤 지침 파일이 언제 왜 로드됐는지 기록할 수 있습니다.

모노레포에서 다른 팀의 CLAUDE.md까지 읽혀 방해가 되면 .claude/settings.local.json의 claudeMdExcludes에 glob을 적어 건너뜁니다. 조직 정책 파일만은 제외할 수 없습니다.

{ "claudeMdExcludes": ["**/other-team/CLAUDE.md"] }

CLAUDE.md와 settings.json은 무엇이 다른가

같은 네 층 구조를 갖지만 동작이 정반대입니다. CLAUDE.md는 어느 파일도 다른 파일을 덮지 않고, settings.json은 층이 높은 쪽이 낮은 쪽을 덮습니다. "이 파일은 절대 읽지 마라"는 CLAUDE.md에 적으면 부탁이고 settings.json의 permissions.deny에 적으면 차단입니다. 조직 정책도 마찬가지로 행동 지침은 관리 CLAUDE.md에, 기술적 강제는 관리 settings에 둡니다.

정리

• 네 곳 모두 읽히고 이어 붙습니다. 충돌은 우선순위로 해결되지 않으므로 충돌 자체를 없앱니다.
• 팀 규칙은 CLAUDE.md, 개인 습관은 ~/.claude/CLAUDE.md, 이 프로젝트만의 개인 값은 CLAUDE.local.md(gitignore 직접 추가)입니다.
• 하위 폴더 CLAUDE.md는 그 폴더 파일을 읽을 때 로드됩니다.
• 확인은 /context의 Memory files 목록, 편집은 /memory, 강제는 settings.json입니다.

자주 묻는 질문