Ch2. CLAUDE.md 마스터하기

CLAUDE.md는 Claude Code가 세션 시작 시 로드하는 **프로젝트 메모리(지침서)**입니다. 프로젝트 규칙을 한 번 정리해두면 반복 프롬프트가 크게 줄어듭니다.

로딩 순서와 계층 구조

Claude Code는 여러 위치의 메모리를 모두 로드합니다. 어느 하나가 다른 것을 덮어쓰지 않고, 모두 컨텍스트에 이어 붙습니다. 공식 문서 기준 로드 순서는 가장 넓은 범위에서 가장 구체적인 범위 순이라, 더 구체적인 메모리가 컨텍스트에서 나중에 등장합니다. 관리 정책 → 사용자 지침 → 프로젝트 지침 → 로컬 지침 순서입니다.

자동 메모리 (Auto memory)

Claude가 세션 중 유용한 컨텍스트(빌드 명령, 디버깅 인사이트, 코드 스타일 선호 등)를 발견하면 자동으로 메모리에 저장합니다. 매 세션 무언가를 반드시 저장하는 것은 아니며, "다음 대화에서 쓸모 있을지"를 기준으로 Claude가 판단합니다. (v2.1.59 이상 필요)

• 저장 위치: ~/.claude/projects/<project>/memory/. <project>는 git 저장소 기준으로 산출되므로, 같은 저장소의 모든 worktree·하위 디렉토리가 하나의 자동 메모리 디렉토리를 공유합니다. (머신 로컬 — 다른 머신·클라우드와는 공유되지 않음)
• 진입점: 디렉토리 안의 MEMORY.md가 인덱스 역할을 하며, 매 세션 시작 시 **처음 200줄 또는 25KB(둘 중 먼저 도달하는 한도)**만 로드됩니다. 세부 노트는 debugging.md 같은 주제 파일로 분리되어 필요할 때 온디맨드로 읽힙니다.
• 켜기/끄기: 기본값은 켜짐. /memory의 토글 또는 프로젝트 설정 autoMemoryEnabled: false로 끌 수 있고, 환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1로도 비활성화됩니다.
• 저장 경로 변경: 사용자 설정(~/.claude/settings.json)의 autoMemoryDirectory로 변경할 수 있습니다(절대 경로 또는 ~/로 시작). 보안상 프로젝트/로컬 설정에서는 받지 않고 정책·사용자 설정과 --settings 플래그에서만 허용됩니다.

HTML 주석과 자동 주입

블록 수준 HTML 주석(<!-- ... -->)은 CLAUDE.md가 컨텍스트에 자동 주입될 때 제거됩니다. 컨텍스트 토큰을 소비하지 않고 사람 유지보수자에게 메모를 남길 때 쓰면 됩니다. 단, 코드 블록 안의 주석은 보존되며, Read 도구로 파일을 직접 열면 주석이 그대로 보입니다.

/init으로 자동 생성

claude
/init

/init은 프로젝트 구조를 분석해 빌드·테스트 명령과 프로젝트 규칙이 담긴 CLAUDE.md 초안을 생성합니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선 제안을 합니다. CLAUDE_CODE_NEW_INIT=1을 설정하면 대화형 다단계 흐름이 활성화되어, 어떤 산출물(CLAUDE.md·skills·hooks)을 설정할지 묻고 subagent로 코드베이스를 탐색한 뒤 파일을 쓰기 전에 검토 가능한 제안을 보여줍니다.

모듈형 규칙: .claude/rules/

큰 프로젝트는 한 파일에 규칙을 몰아넣기보다 주제별 규칙 파일로 분리하는 것이 좋습니다. .claude/rules/ 안의 모든 .md 파일은 재귀적으로 발견되며, paths: frontmatter가 없는 규칙은 .claude/CLAUDE.md와 동일한 우선순위로 시작 시 로드됩니다.

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    └── security.md

frontend/, backend/ 같은 하위 디렉토리로 정리해도 모두 인식됩니다. ~/.claude/rules/에 두는 사용자 수준 규칙은 머신의 모든 프로젝트에 적용되며, 사용자 규칙이 먼저 로드되고 프로젝트 규칙이 더 높은 우선순위를 가집니다.

조건부 규칙 파일 (path-specific rules)

.claude/rules/*.md 파일에 paths: frontmatter를 지정하면 해당 glob 패턴에 맞는 파일을 Claude가 읽을 때만 규칙이 적용됩니다(모든 도구 사용 시가 아님). paths가 없으면 무조건 로드되어 모든 파일에 적용됩니다.

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.{ts,tsx}"
---

# API 개발 규칙

- 모든 API 엔드포인트는 입력 검증을 포함
- 표준 오류 응답 형식 사용

InstructionsLoaded 훅 이벤트

CLAUDE.md 또는 .claude/rules/*.md 파일이 컨텍스트에 로드될 때 InstructionsLoaded 훅 이벤트가 발생합니다. 세션 시작 시 즉시 로드되는 파일은 물론, 하위 디렉토리의 중첩 CLAUDE.md나 paths: 조건이 매칭되어 지연 로드되는 경우에도 발생합니다. 이 훅은 관찰(observability) 전용으로, 감사 로깅·컴플라이언스 추적·모니터링에 쓰이며 로딩을 차단하거나 내용을 수정할 수는 없습니다. 입력으로 file_path, memory_type(User/Project/Local/Managed), load_reason(session_start/nested_traversal/path_glob_match/include/compact) 등을 받으며, matcher는 load_reason에 대해 동작합니다(예: "matcher": "session_start").

${CLAUDE_SKILL_DIR} 변수

스킬의 bash injection 명령 안에서 ${CLAUDE_SKILL_DIR}를 사용하면 해당 스킬의 SKILL.md가 들어 있는 디렉토리를 참조할 수 있습니다(플러그인 스킬의 경우 플러그인 루트가 아니라 스킬 하위 디렉토리). 상대 경로 대신 이 변수를 쓰면 현재 작업 디렉토리와 무관하게 스킬 번들의 스크립트·파일을 안정적으로 참조할 수 있습니다.

python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

includeGitInstructions 설정

설정 includeGitInstructions(기본값 true)를 false로 지정하면 커밋/PR 워크플로우에 대한 기본 지시사항이 시스템 프롬프트에서 제거됩니다. 환경 변수 CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1로도 같은 효과를 낼 수 있으며, 이 환경 변수는 설정값보다 우선합니다. 독자적인 Git 워크플로우 규칙(스킬 등)을 사용하는 팀에게 유용합니다.

대규모 팀·조직 관리

조직 전체 CLAUDE.md 배포

관리 정책 위치(위 표 참조)에 CLAUDE.md를 두면 머신의 모든 세션·저장소에 적용되며, 개별 설정으로 제외할 수 없습니다. MDM·그룹 정책·Ansible 등으로 배포합니다. 별도 파일 대신 managed-settings.json의 claudeMd 키에 내용을 직접 넣을 수도 있습니다(관리·정책 설정에서만 적용됨).

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

특정 CLAUDE.md 제외

모노레포에서 상위 디렉토리의 관계없는 CLAUDE.md가 끌려오면, claudeMdExcludes 설정에 경로/glob을 넣어 건너뛸 수 있습니다(절대 경로 기준 매칭). 보통 .claude/settings.local.json에 두어 머신 로컬로 유지합니다. 단, 관리 정책 CLAUDE.md는 제외되지 않습니다.

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

추가 디렉토리에서 메모리 로드

--add-dir로 추가한 디렉토리의 CLAUDE.md는 기본적으로 로드되지 않습니다. CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1을 설정하면 추가 디렉토리의 CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, CLAUDE.local.md까지 로드됩니다.

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

REVIEW.md (Code Review 전용)

Code Review 기능을 사용하는 팀은 리포지토리 **루트에 REVIEW.md**를 추가하면 리뷰 전용 규칙을 정의할 수 있습니다. CLAUDE.md와 달리 리뷰 시에만 적용되며, 그 내용은 리뷰 파이프라인의 모든 에이전트 시스템 프롬프트에 최고 우선순위 지시 블록으로 그대로 주입됩니다. verbatim으로 붙기 때문에 REVIEW.md 안에서는 @ import 구문이 확장되지 않습니다 — 규칙을 파일에 직접 적어야 합니다. "무엇을 어떤 심각도로 플래그할지", "어떤 경로는 건너뛸지", "PR마다 항상 확인할 것" 등을 정리하기에 적합합니다.

@import로 외부 파일 포함

CLAUDE.md에서 다른 파일을 @path/to/import 구문으로 가져올 수 있습니다. 가져온 파일은 확장되어 시작 시 함께 컨텍스트에 로드됩니다.

## 참고 자료
- API 규칙은 @docs/api-conventions.md 참조
- 개인 규칙은 @~/.claude/my-project-instructions.md 참조

• 상대/절대 경로 모두 지원 (상대 경로는 작업 디렉토리가 아니라 import를 포함한 파일 기준으로 해석)
• 코드 블록/인라인 코드 안의 @는 무시됨
• 재귀 import는 **최대 4단계(four hops)**까지
• 프로젝트에서 외부 import를 처음 만나면 승인 대화가 뜨며, 거부하면 import가 비활성화됩니다
• import 해도 컨텍스트 절약 효과는 없습니다(가져온 파일도 시작 시 전부 로드). 컨텍스트를 줄이려면 paths: 조건부 규칙을 쓰세요

즉석 메모리 추가: # 단축키와 /memory

세션 중 무언가를 기억시키고 싶다면 두 가지 방법이 있습니다.

• 입력 첫 줄을 #로 시작하면 어느 메모리에 저장할지 선택할 수 있습니다.

  # 앞으로 테스트 파일은 __tests__ 폴더에 작성해줘

• 또는 Claude에게 직접 "이건 기억해줘"라고 요청하면 자동 메모리에 저장됩니다. CLAUDE.md에 넣고 싶다면 "이걸 CLAUDE.md에 추가해줘"라고 하거나 /memory로 파일을 직접 편집합니다.

/memory 명령은 현재 세션에 로드된 모든 CLAUDE.md·CLAUDE.local.md·규칙 파일을 나열하고, 자동 메모리 토글과 자동 메모리 폴더 링크를 제공합니다.

/compact와 메모리 보존

압축 시 반드시 남기고 싶은 핵심 컨텍스트는 별도 섹션으로 모아두면 관리가 쉽습니다.

## Compact Instructions

이 프로젝트는 Next.js + Tailwind 모노레포.
- apps/web: 프론트엔드
- apps/api: 백엔드
- 한국어 응답, 커밋 금지(명시 요청 전)

실전 예시

# CLAUDE.md

## Commands
yarn dev

yarn build

yarn lint

## Architecture
- app/: 라우팅
- lib/: 비즈니스 로직

## Code Style
- TypeScript strict
- 함수형 컴포넌트

## Compact Instructions
Next.js + Tailwind. 한국어 응답.

참고 문서

• Claude Code 메모리 구조와 로딩 규칙: https://code.claude.com/docs/ko/memory (한국어)
• 슬래시 커맨드 목록 (/init, /memory, /compact 등): https://code.claude.com/docs/ko/commands (한국어)