Files

lacvet deffb33cf9 Initial commit to new repository

2026-04-03 18:23:52 +09:00

7.0 KiB

Raw Permalink Blame History

메모리와 컨텍스트 (CLAUDE.md)

Claude Code가 CLAUDE.md 메모리 파일을 어떻게 발견하고, 로드하고, 우선순위를 결정하는지 설명합니다.

Claude Code는 일반 마크다운 파일 기반의 계층적 메모리 시스템을 지원합니다. 파일 시스템의 여러 레벨에 있는 CLAUDE.md 파일에 지시사항을 작성해서 Claude의 동작을 전역적으로, 프로젝트별로, 또는 사용자별로 커스터마이징할 수 있습니다.

4단계 메모리 계층

메모리 파일은 다음 순서로 로드됩니다(낮은 우선순위 → 높은 우선순위). 나중에 로드된 파일이 우선합니다. 컨텍스트 윈도우에서 나중에 나타나는 지시사항에 모델이 더 주의를 기울이기 때문입니다.

1단계: Managed 메모리 (최저 우선순위)

경로: /etc/claude-code/CLAUDE.md
관리자 또는 배포 도구가 설정한 시스템 전체 지시사항. 머신의 모든 사용자에게 적용됩니다.

2단계: User 메모리

경로: ~/.claude/CLAUDE.md 및 ~/.claude/rules/*.md
모든 프로젝트에 적용되는 개인 전역 지시사항. 선호하는 코드 스타일, 기본 언어, git 사용자명 등 개인 설정에 적합합니다. 이 파일은 어떤 저장소에도 커밋되지 않습니다.

3단계: Project 메모리

경로(CWD까지 각 상위 디렉토리에서 확인): CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md
팀 전체가 공유하는 코드베이스에 커밋된 지시사항. 프로젝트 컨벤션, 아키텍처 노트, 테스트 커맨드에 이상적입니다.

4단계: Local 메모리 (최고 우선순위)

경로: CLAUDE.local.md (각 상위 디렉토리에서 확인)
.gitignore에 추가해야 하는 개인 프로젝트별 재정의. 로컬 환경 경로, 개인 디버깅 노트 등에 사용합니다.

📝 현재 작업 디렉토리에 더 가까운 파일이 나중에 로드되어 더 높은 우선순위를 가집니다. 프로젝트 루트의 CLAUDE.md가 상위 디렉토리의 것보다 우선합니다.

파일 발견 알고리즘

Claude Code 시작 시, 현재 작업 디렉토리에서 파일시스템 루트까지 올라가며 각 레벨의 메모리 파일을 수집합니다. 발견 순서는 낮은 우선순위 파일이 먼저 조립된 컨텍스트에 나타나도록 보장합니다:

Managed 파일이 먼저 로드됩니다
User 파일이 다음으로 로드됩니다
Project 및 Local 파일은 루트에서 CWD로 내려가며 반복됩니다 — 상위 디렉토리가 하위 디렉토리보다 먼저 옵니다

📝 발견된 파일 목록은 대화 기간 동안 메모이제이션됩니다. /memory를 실행해 메모리 에디터를 열고 강제 리로드하거나, 세션을 재시작해 Claude Code 외부에서 만들어진 변경 사항을 반영합니다.

`@include` 지시어

메모리 파일은 @ 표기법으로 다른 파일을 참조할 수 있습니다. 참조된 파일은 포함하는 파일 이전에 별도 항목으로 컨텍스트에 삽입됩니다.

# My project CLAUDE.md

@./docs/architecture.md
@./docs/conventions/typescript.md

커밋 전에 항상 `bun test`를 실행하세요.

구문	해석
`@filename`	포함하는 파일 디렉토리 기준 상대 경로
`@./relative/path`	명시적 상대 경로
`@~/home/path`	사용자 홈 디렉토리 기준 경로
`@/absolute/path`	절대 경로

규칙:

코드 블록 및 인라인 코드 안의 @include는 무시됩니다
순환 참조는 감지되어 건너뜁니다
존재하지 않는 파일은 조용히 무시됩니다
최대 include 깊이는 5단계입니다
텍스트 기반 파일 형식만 포함됩니다(.md, .ts, .py, .json 등). 이미지와 PDF 같은 바이너리 파일은 건너뜁니다

`.claude/rules/*.md` — 세분화된 규칙 파일

모든 것을 하나의 큰 CLAUDE.md에 넣는 대신, .claude/rules/ 안의 여러 마크다운 파일로 지시사항을 나눌 수 있습니다:

my-project/
├── CLAUDE.md
└── .claude/
    └── rules/
        ├── testing.md
        ├── typescript-style.md
        └── git-workflow.md

모든 .md 파일은 자동으로 로드됩니다. 규칙 파일은 경로 범위 프론트매터도 지원합니다:

---
paths:
  - "src/api/**"
  - "src/services/**"
---

항상 의존성 주입을 사용하세요. 구체적인 구현을 직접 import하지 마세요.

paths가 설정되면, 규칙 파일은 Claude가 해당 glob 패턴과 일치하는 파일을 작업할 때만 컨텍스트에 주입됩니다. 대규모 프로젝트에서 컨텍스트를 간결하게 유지합니다.

최대 파일 크기

단일 메모리 파일의 권장 최대 크기는 40,000자입니다. 이 한계를 초과하는 파일은 플래그 처리되고, Claude가 전체 내용을 읽지 못할 수 있습니다. 메모리 파일은 집중적이고 간결하게 유지하세요.

메모리가 Claude 동작에 미치는 영향

메모리 파일이 로드되면, 다음과 같은 프리픽스가 붙은 단일 컨텍스트 블록으로 조립됩니다:

"Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written."

즉, CLAUDE.md 파일의 지시사항이 Claude의 내장 기본값보다 우선합니다. 이를 활용해 프로젝트 컨벤션을 강제하거나, 특정 작업을 제한하거나, 도메인 지식을 주입할 수 있습니다.

각 레벨 사용 지침

레벨	용도
Managed 메모리	모든 사용자가 따라야 하는 조직 전체 정책, 보안 가이드라인
User 메모리 (`~/.claude/CLAUDE.md`)	모든 프로젝트에 걸쳐 적용되는 개인 선호도: 응답 언어, 커밋 메시지 스타일
Project 메모리 (`CLAUDE.md`)	팀과 공유하는 프로젝트 컨벤션: 테스트 실행 방법, 빌드 커맨드, 아키텍처 결정
Local 메모리 (`CLAUDE.local.md`)	특정 프로젝트의 개인 재정의: 로컬 환경 경로, 개인 디버깅 노트

`/memory` 커맨드

Claude Code REPL 안에서 /memory를 실행해 메모리 파일 에디터를 엽니다. 현재 로드된 메모리 파일을 보여주고, 직접 편집하며, 저장 시 컨텍스트를 리로드합니다.

💡 Claude에게 직접 물어볼 수도 있습니다: "CLAUDE.md에 항상 2칸 들여쓰기를 사용한다는 규칙을 추가해줘." Claude가 적절한 메모리 파일을 찾아 지시사항을 작성합니다.

메모리 로딩 비활성화

방법	효과
`CLAUDE_CODE_DISABLE_CLAUDE_MDS=1`	모든 메모리 파일 로딩 완전 비활성화
`--bare` 플래그	CWD 워크에서 메모리 파일 자동 발견 건너뜀
`claudeMdExcludes` 설정	건너뛸 메모리 파일 경로의 Glob 패턴

7.0 KiB Raw Permalink Blame History