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

CLAUDE.md는 프로젝트 루트 한 곳이 아니라 조직 정책·사용자 홈·프로젝트 루트·CLAUDE.local.md 네 곳에 둘 수 있는 파일이며, 넓은 범위부터 좁은 범위 순으로 전부 읽혀 컨텍스트에 이어 붙습니다. 배치 장소를 가려 쓰면 팀과 공유할 규칙과 나만의 설정을 섞이지 않게 관리할 수 있습니다. CLAUDE.md 작성법이 "무엇을 적을까"라면, 이 글은 "어디에 적을까"를 다룹니다.

핵심 요약

• CLAUDE.md는 네 곳에 배치할 수 있고, 읽기 순서가 정해져 있습니다
• 어느 하나만 적용되는 것이 아니라 전부 연결되어 컨텍스트에 들어갑니다
• ~/.claude/CLAUDE.md에 적은 개인 설정은 모든 프로젝트에 적용됩니다
• CLAUDE.local.md로 팀 공유와 분리된 개인 설정을 둘 수 있습니다(.gitignore는 직접 추가)
• /memory와 /context로 지금 읽힌 파일과 토큰 소비를 확인합니다

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

Claude Code는 다음 순서로 CLAUDE.md를 읽습니다.

여기서 꼭 기억할 점이 하나 있습니다. 이 파일들은 어느 하나가 선택되는 것이 아니라 전부 이어 붙어 컨텍스트에 들어갑니다. 읽기 순서는 범위가 넓은 것에서 좁은 것으로 나열돼 있고, 더 구체적인 범위일수록 나중에 읽힙니다. 그래서 같은 주제를 두 곳에 적어 두면 한쪽이 자동으로 무효가 되는 게 아니라 양쪽이 모두 Claude에게 전달됩니다.

Managed policy는 조직용 기능이라 개인 이용에서는 보통 신경 쓸 필요가 없습니다. macOS는 /Library/Application Support/ClaudeCode/CLAUDE.md, Linux는 /etc/claude-code/CLAUDE.md에 둡니다.

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

배치 장소는 네 곳이지만, 조직 정책을 빼면 실제 개발에서 의식할 패턴은 세 가지입니다.

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

프로젝트 루트의 CLAUDE.md는 팀원 전원이 공유하는 내용을 적는 곳입니다. Git으로 관리하면 팀 전원이 같은 설정으로 Claude Code를 씁니다.

my-project/
├── CLAUDE.md          # ← 팀 공유 (Git 관리)
├── src/
└── package.json

여기에 들어갈 내용은 다음과 같습니다.

• 프로젝트 개요와 목적
• 기술 스택(언어, 프레임워크, 라이브러리)
• 코딩 규약(명명 규칙, 포맷)
• 자주 쓰는 개발 명령(npm run dev, npm test 등)

무엇을 어떤 구조로 적을지는 CLAUDE.md 실전 템플릿의 "개요·명령·규칙·금지" 네 블록을 그대로 쓰면 됩니다.

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

어느 프로젝트에서 작업하든 똑같이 지키고 싶은 개인 스타일은 ~/.claude/CLAUDE.md에 둡니다.

mkdir -p ~/.claude
nano ~/.claude/CLAUDE.md

# 개인 설정

## 기본 방침
- 커밋 메시지는 한국어로 쓴다
- 테스트를 먼저 쓴 뒤 코드를 구현한다 (TDD)
- 복잡한 로직에는 주석을 반드시 추가한다

응답 언어, 설명 눈높이, 커밋 메시지 언어처럼 "프로젝트와 무관하게 나에게 늘 해당하는 것"이 이 파일의 자리입니다.

주의할 점은 모순입니다. 사용자 레벨 설정은 프로젝트 루트 설정보다 먼저 읽히므로 프로젝트 쪽 지시가 더 가까운 문맥으로 다뤄지기 쉽지만, 내용이 충돌하면 Claude가 어느 쪽을 따를지 일정하지 않습니다. 예를 들어 사용자 레벨에 "세미콜론 없음", 프로젝트에 "세미콜론 필수"라고 적혀 있으면 결과가 흔들립니다. 어느 파일에 무엇을 쓸지 역할을 나눠 두고, 프로젝트 규칙과 부딪힐 만한 코드 스타일은 사용자 레벨에 적지 않는 편이 안전합니다.

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

팀과 공유하고 싶지 않은 개인 메모나, 내 로컬 환경에만 해당하는 정보는 CLAUDE.local.md에 둡니다.

my-project/
├── CLAUDE.md          # 팀 공유 (Git 관리)
├── CLAUDE.local.md    # 개인용 (Git 관리 제외)
├── src/
└── package.json

# 로컬 설정

## 개발 환경
- 샌드박스 URL: http://localhost:3000
- 테스트용 DB: postgresql://localhost:5432/myapp_dev
- API 목 서버: http://localhost:4000

한 가지 함정이 있습니다. CLAUDE.local.md는 자동으로 .gitignore에 추가되지 않습니다. 팀에 공유되지 않게 하려면 직접 .gitignore에 넣어야 합니다. 로컬 DB 주소 같은 값이 실수로 커밋되는 일을 막으려면 파일을 만들 때 바로 추가해 두세요.

# .gitignore
CLAUDE.local.md

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

세 패턴을 실제로 조합하면 다음 두 가지 형태가 대부분입니다.

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

CLAUDE.md           # 팀 공유 (Git 관리)
CLAUDE.local.md     # 개인용 (Git 관리 제외)

CLAUDE.md (팀 공유)

# MyProject

## 기술 스택
- Next.js 14 + TypeScript
- PostgreSQL + Prisma

## 코딩 규약
- 명명 규칙은 camelCase
- 테스트 커버리지는 80% 이상

CLAUDE.local.md (개인용)

# 로컬 설정

## 개발 환경
- 로컬 DB URL: postgresql://localhost:5432/myproject_dev
- 개발 서버: http://localhost:3000

팀 규칙은 저장소에 남고, 포트 번호나 DB 주소처럼 사람마다 다른 값은 각자 파일에 머뭅니다.

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

프로젝트마다 반복해서 적던 개인 스타일은 사용자 레벨로 올립니다.

# ~/.claude/CLAUDE.md

## 코딩 스타일
- 인덴트: 스페이스 2개
- 쿼트: 싱글

## 커밋
- Conventional Commits를 따른다
- feat:, fix:, docs: 등의 접두사를 사용한다

프로젝트 고유 규칙은 각 저장소의 CLAUDE.md에, 공통 스타일은 사용자 레벨에 두는 분담입니다. 단, 앞서 말한 대로 프로젝트 규칙과 충돌할 여지가 있는 항목은 사용자 레벨에서 빼는 것이 좋습니다.

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

설정이 기대대로 들어갔는지 확인하는 명령이 두 개 있습니다.

/memory — 읽힌 파일 목록과 편집

/memory

실행하면 배치 장소별로 나뉜 선택 화면이 나옵니다.

  Memory
    Auto-memory: off
  ❯ 1. User instructions     Saved in ~/.claude/CLAUDE.md
    2. Project instructions  Saved in ./CLAUDE.md
  Learn more: https://code.claude.com/docs/en/memory
  Enter to confirm · Esc to cancel

어느 설정을 고칠지 골라 바로 편집할 수 있습니다.

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

/context

출력 가운데 Memory files 항목을 보면 읽힌 파일과 각 파일이 소비하는 토큰 수가 나옵니다.

  ⎿  Memory files · /memory
  ⎿  └ User (~/.claude/CLAUDE.md): 1.5k tokens
  ⎿  └ Project (./CLAUDE.md): 663 tokens

사용자 레벨 파일이 의외로 크게 잡혀 있다면 그만큼 매 세션 고정 비용을 내고 있다는 뜻입니다. 기타 명령은 기본 조작과 명령어를, 토큰 예산 관리는 컨텍스트 윈도우 관리를 참고하세요.

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

"배치 장소에 따른 우선순위"라는 구조는 settings.json도 비슷해서 혼동하기 쉽습니다. 역할은 분명히 다릅니다.

CLAUDE.md에 쓸 것

• 프로젝트 개요·목적
• 코딩 규약·스타일 가이드
• 해줬으면 하는 것, 하지 말았으면 하는 것

settings.json에 쓸 것

• 퍼미션 설정(허용할 Bash 명령 등)
• 훅(Hooks) 설정
• MCP 서버 승인 설정(enabledMcpjsonServers 등)

"이 명령은 묻지 말고 실행해"는 CLAUDE.md에 적어도 강제되지 않습니다. 그런 것은 settings.json의 퍼미션이 맡습니다. 둘은 보완 관계입니다.

정리

• CLAUDE.md는 조직 정책 → 사용자 홈 → 프로젝트 루트 → CLAUDE.local.md 순으로 전부 읽혀 이어 붙습니다
• 팀 규칙은 루트 CLAUDE.md, 개인 공통 스타일은 ~/.claude/CLAUDE.md, 로컬 환경 값은 CLAUDE.local.md에 둡니다
• CLAUDE.local.md는 .gitignore에 직접 추가해야 합니다
• 두 파일의 지시가 모순되면 결과가 흔들리므로 역할을 나눠 적습니다
• /memory로 읽힌 파일을, /context로 토큰 소비를 확인합니다

우선 프로젝트 루트의 CLAUDE.md부터 정비하고, 필요해질 때 사용자 레벨과 CLAUDE.local.md를 더해 가는 순서를 권합니다. 루트 파일이 길어지기 시작하면 사양서는 @참조로 빼고, 조건부 규칙은 .claude/rules/로 나누면 됩니다.