CLAUDE.md (Claude Code 영구 지시어 파일)
Term (용어)aiverifiedFri May 01

CLAUDE.md (Claude Code 영구 지시어 파일)

별칭: CLAUDE.md · claudemd · 클로드 md

#claudemd#claude-code#persistent-instructions#anthropic#design-language

정의

entity/claude-code 가 매 세션 시작 시 자동으로 로드 하는 프로젝트별 영구 지시어 파일. 파일명은 정확히 CLAUDE.md (대소문자 그대로). 위치는 프로젝트 루트 또는 ~/.claude/CLAUDE.md (글로벌).

Anthropic 공식 정의

"매 세션 시작 시 자동으로 로드되는 프로젝트 기억(persistent project memory)" — Claude Code Best Practices (case/anthropic-best-practices)

작동 원리

  1. Claude Code 가 시작되면 현재 디렉터리부터 상위로 거슬러 올라가며 CLAUDE.md 를 자동 탐색·로드.
  2. ~/.claude/CLAUDE.md (글로벌) 도 함께 로드.
  3. 두 파일의 내용이 시스템 프롬프트 의 일부로 모든 세션에 주입됨.
  4. 사용자가 매 세션마다 반복 입력할 필요 없는 지속적 컨텍스트.

좋은 CLAUDE.md 의 특징 (공식 가이드)

  • Specific: 구체적 — use TypeScript 보다 use TypeScript 5.x with strict mode.
  • Concise: 간결 — 불필요한 산문 제거.
  • Well-structured: 잘 구조화 — 목차·섹션·표 활용.

자매 도구의 등가물

도구영구 지시어 파일
entity/claude-codeCLAUDE.md
entity/cursorterm/cursorrules (.cursorrules)
entity/github-copilotterm/agents-md (AGENTS.md)

강의 활용

  • 01 INT case/anthropic-best-practices: 첫 등장 — 매 세션 자동 로드 의 의미 설명.
  • 04 DSL: 본격 작성 사례 + 세 도구 비교.
  • 05 DEM: 시연 프로젝트의 실제 CLAUDE.md 화면 공개.

주의사항

  • 파일명 대소문자: CLAUDE.md (전체 대문자). claude.md / Claude.md 는 불인식.
  • 글로벌 vs 프로젝트: 두 위치가 모두 로드되므로 충돌 시 프로젝트 파일이 우선. 강의에서 명확 구분.
  • 메모리 vs 단순 메모: 매번 리로드되는 설계 문서 라는 점이 핵심. 단순 README와 혼동 금지.