3.1CLAUDE.md 계층 구조

Claude Code는 매 세션 시작 시 여러 위치의 CLAUDE.md 파일을 찾아 컨텍스트에 포함합니다. 각 위치는 서로 다른 범위(scope)를 가집니다.

종류	위치	범위	공유 여부
엔터프라이즈 정책	시스템 관리 디렉터리 (예: macOS /Library/Application Support/ClaudeCode/CLAUDE.md)	조직 전체	관리자가 배포
사용자 메모리	~/.claude/CLAUDE.md	모든 프로젝트	개인 전용
프로젝트 메모리	<저장소 루트>/CLAUDE.md	해당 저장소	커밋하여 팀과 공유
하위 디렉터리 메모리	<저장소>/서브디렉터리/CLAUDE.md	해당 디렉터리 작업 시	커밋하여 팀과 공유

사용자 메모리에는 개인 취향(코딩 스타일, 언어 설정)을, 프로젝트 메모리에는 팀 공통 규칙(빌드 명령, 아키텍처 규칙, 테스트 실행법)을 둡니다.

# CLAUDE.md (프로젝트 루트)

## 빌드와 테스트
- 빌드: npm run build
- 단위 테스트: npm run test:unit
- 커밋 전 반드시 lint 통과: npm run lint

## 아키텍처 규칙
- API 핸들러는 src/api/ 아래에만 둔다
- 공용 타입은 src/lib/types.ts 에 모은다

중요한 특징 하나: 하위 디렉터리의 CLAUDE.md는 세션 시작 시 전부 로드되는 것이 아니라, Claude가 해당 디렉터리의 파일을 읽거나 수정할 때 필요 시점에(on demand) 로드됩니다. 따라서 모노레포(monorepo)에서 패키지별 규칙을 하위 CLAUDE.md로 분리하면 불필요한 컨텍스트 소비를 줄일 수 있습니다.

여러 CLAUDE.md가 동시에 존재하면 모두 컨텍스트에 포함되지만, 지침이 충돌할 때는 더 구체적인 범위가 우선한다는 원칙으로 이해하면 됩니다. 로드 순서는 상위(일반적)에서 하위(구체적) 방향입니다.

1. 엔터프라이즈 정책 — 조직 관리자가 강제하는 규칙
2. 사용자 메모리(~/.claude/CLAUDE.md) — 개인 공통 규칙
3. 프로젝트 메모리(저장소 루트) — 팀 공통 규칙
4. 하위 디렉터리 메모리 — 특정 패키지·모듈 규칙

예를 들어 사용자 메모리에 "들여쓰기는 탭"이라고 적었더라도, 프로젝트 CLAUDE.md에 "이 저장소는 스페이스 2칸"이라고 적혀 있으면 프로젝트 쪽을 따르는 것이 기대 동작입니다. 시험에서는 이 우선순위의 방향(구체적 > 일반적)을 뒤집어 놓은 선택지가 자주 나옵니다.

또 하나 주의할 점은 CLAUDE.md가 모델에 주는 지침이지 하드 제약이 아니라는 것입니다. 반드시 강제해야 하는 규칙(예: 특정 명령 실행 금지)은 메모리 파일이 아니라 권한 설정(settings.json의 permissions)이나 훅(hooks)으로 걸어야 합니다.

# 현재 세션에 로드된 메모리 파일을 확인
/memory

# 대화 중 즉시 메모리에 규칙 추가 (# 단축키)
# 항상 한국어로 답해줘

/memory 명령으로 어떤 파일이 로드됐는지 확인하고 편집할 수 있으며, 메시지를 #으로 시작하면 해당 내용을 어느 메모리 파일에 저장할지 물어본 뒤 기록합니다.

CLAUDE.md가 커지면 컨텍스트를 낭비하고 유지보수가 어려워집니다. 임포트(import) 문법 @경로를 사용하면 다른 파일을 참조하여 내용을 분리할 수 있습니다.

# CLAUDE.md

프로젝트 개요는 @README.md 를 참고.
자세한 API 규칙은 @docs/api-guidelines.md 참고.
개인 로컬 설정: @~/.claude/my-project-prefs.md

임포트 규칙은 다음과 같습니다.

• 상대 경로와 절대 경로, 홈 디렉터리(~) 경로를 모두 쓸 수 있습니다.
• 임포트된 파일이 다시 다른 파일을 임포트할 수 있으며, 재귀 깊이는 최대 5단계입니다.
• 코드 스팬이나 코드 블록 안의 @경로는 임포트로 처리되지 않습니다. 예를 들어 npm install @types/node 같은 패키지명은 안전합니다.

모듈화의 실전 패턴은 이렇습니다. 루트 CLAUDE.md에는 어떤 프로젝트에서도 필요한 핵심 규칙(빌드·테스트 명령, 금지 사항)만 짧게 남기고, 길어지는 상세 규칙은 주제별 파일로 나눈 뒤 임포트합니다. 팀원 개인의 로컬 전용 규칙은 저장소에 커밋하지 않는 홈 디렉터리 파일을 임포트하도록 하면, 과거에 쓰이던 CLAUDE.local.md 방식보다 유연하게 개인 설정을 분리할 수 있습니다.

새 프로젝트에서는 /init 명령을 실행하면 Claude가 코드베이스를 훑어보고 초기 CLAUDE.md 초안을 생성해 줍니다. 생성된 초안은 그대로 두지 말고, 팀이 실제로 강제하고 싶은 규칙 중심으로 다듬는 것이 좋습니다.

CLAUDE.md는 모든 세션의 컨텍스트에 포함되므로, 길이 대비 효과가 높아야 합니다. 잘 작성하는 원칙은 다음과 같습니다.

짧고 구체적으로. "좋은 코드를 작성하라" 같은 일반론은 토큰만 소비합니다. "2칸 들여쓰기 사용", "테스트는 vitest로 실행" 같이 행동을 바꾸는 구체적 지침만 남깁니다.

구조화하라. 마크다운 불릿과 섹션 제목으로 구조화하면 모델이 규칙을 놓치지 않습니다. 서술형 문단보다 목록이 낫습니다.

자주 틀리는 것을 기록하라. Claude가 반복적으로 잘못하는 부분(예: 잘못된 테스트 명령 사용)을 발견할 때마다 # 단축키로 추가하고, 주기적으로 다듬습니다. CLAUDE.md는 한 번 쓰고 끝나는 문서가 아니라 프롬프트처럼 계속 개선하는 살아 있는 문서입니다.

강제가 필요한 것은 메모리 밖으로. 절대 어기면 안 되는 규칙은 permissions나 hooks로 옮깁니다. 메모리는 지침(guidance), 설정은 강제(enforcement)라는 구분이 시험의 단골 주제입니다.

## 나쁜 예
코드를 작성할 때는 항상 모범 사례를 따르고 깨끗하게 작성해 주세요.

## 좋은 예
- 테스트 실행: npm run test (jest 아님, vitest임)
- import 정렬은 eslint가 처리하므로 수동 정렬 금지
- DB 마이그레이션 파일은 절대 수정하지 말고 새 파일 추가