Ch2. CLAUDE.md 마스터하기

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

로딩 순서와 계층 구조

Claude Code는 여러 위치의 메모리를 모두 로드합니다. 상위 범주의 메모리가 기본 토대를 만들고, 더 구체적인 메모리가 그 위에 쌓입니다.

자동 메모리 기록

Claude가 세션 중 유용한 컨텍스트를 발견하면 자동으로 메모리에 저장합니다. 별도의 # 단축키 없이도 프로젝트 패턴이나 규칙이 축적되어, 다음 세션에서 더 정확한 응답을 얻을 수 있습니다. (v2.1.59)

HTML 주석과 자동 주입

HTML 주석(<!-- ... -->)은 CLAUDE.md가 자동 주입될 때 Claude에게 숨겨집니다. Read 도구로 파일을 직접 읽으면 주석이 표시되므로, 사람을 위한 메모와 Claude를 위한 지시를 분리할 수 있습니다. (v2.1.72)

/init으로 자동 생성

claude /init

/init은 프로젝트 구조를 분석해 CLAUDE.md 초안을 생성합니다. 팀 규칙과 아키텍처 결정사항을 추가해 완성도를 높이세요.

모듈형 규칙: .claude/rules/

큰 프로젝트는 한 파일에 규칙을 몰아넣기보다 주제별 규칙 파일로 분리하는 것이 좋습니다. .claude/rules/*.md는 프로젝트 메모리와 동일한 우선순위로 자동 로드됩니다.

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

필요하면 규칙을 디렉토리별로 분리해 적용 범위를 좁힐 수 있습니다.

조건부 규칙 파일

.claude/rules/*.md 파일에 paths: frontmatter를 지정하면 특정 경로에서만 규칙이 적용됩니다. print 모드(-p)에서도 조건부 규칙이 정상적으로 로드됩니다. (v2.1.69)

InstructionsLoaded 훅 이벤트

CLAUDE.md 또는 .claude/rules/*.md 파일이 로드될 때 InstructionsLoaded 훅 이벤트가 발생합니다. 이를 활용해 규칙 로딩 시점에 커스텀 로직을 실행할 수 있습니다. (v2.1.69)

${CLAUDE_SKILL_DIR} 변수

스킬 파일 내에서 ${CLAUDE_SKILL_DIR} 변수를 사용하면 스킬이 자신의 디렉토리를 참조할 수 있습니다. 상대 경로 대신 이 변수를 활용하면 스킬의 이동성이 높아집니다. (v2.1.69)

includeGitInstructions 설정

includeGitInstructions 설정을 false로 지정하면 커밋/PR 워크플로우에 대한 기본 지시사항이 제거됩니다. 독자적인 Git 워크플로우 규칙을 사용하는 팀에게 유용합니다. (v2.1.69)

REVIEW.md (Code Review 전용)

Code Review 기능을 사용하는 팀은 리포지토리 루트에 REVIEW.md를 추가하면 리뷰 전용 규칙을 정의할 수 있습니다. CLAUDE.md와 별개로, Code Review 시에만 적용됩니다 — "항상 체크할 것", "무시할 것" 등을 정리합니다.

@import로 외부 파일 포함

CLAUDE.md에서 다른 파일을 가져올 수 있습니다.

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

• 상대/절대 경로 모두 지원
• 코드 블록/인라인 코드 안의 @는 무시됨
• 최대 5단계까지 재귀 import

# 단축키로 즉석 메모리 추가

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

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

Compact Instructions 섹션

/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://docs.claude.com/ko/docs/claude-code/memory (한국어)
• 슬래시 커맨드 목록 (/init, /memory, /compact 등): https://code.claude.com/docs/ko/slash-commands (한국어)