CLAUDE.md (Claude Code): 파일 위치와 도구별 읽기 방식

CLAUDE.md는 Claude Code가 시작할 때 홈 디렉터리, 프로젝트, 모든 상위 디렉터리에서 불러오는 메모리 파일입니다. .claude/rules/의 경로별 규칙은 일치하는 파일을 읽을 때만 적용되는 추가 지침을 제공합니다.

파일 위치

• 프로젝트: ./CLAUDE.md 또는 ./.claude/CLAUDE.md. 커밋하여 팀과 공유합니다.
• 로컬: ./CLAUDE.local.md. Git에 포함하지 않을 개인 메모에 사용합니다.
• 사용자: ~/.claude/CLAUDE.md. 모든 프로젝트에 적용됩니다.
• 규칙: ./.claude/rules/**/*.md 및 ~/.claude/rules/**/*.md. 필요하면 paths frontmatter로 적용 범위를 지정할 수 있습니다.
• 관리 정책: macOS에서는 /Library/Application Support/ClaudeCode/CLAUDE.md, Windows에서는 C:\Program Files\ClaudeCode\CLAUDE.md 또는 managed-settings.json의 claudeMd 키를 사용합니다.

형식

Markdown 형식입니다. .claude/rules/의 파일은 paths 키에 glob 패턴 목록을 지정하는 YAML frontmatter로 시작할 수 있습니다. @path/to/file로 다른 파일을 포함할 수 있으며 최대 4단계까지 중첩할 수 있습니다. 문서에 명시된 크기 제한은 없지만, Anthropic은 파일당 200줄 미만을 권장합니다.

Frontmatter 키: paths

@AGENTS.md

# Claude Code notes

- Run `pnpm test` after every change under src/.
- Use the `gh` CLI for issues and pull requests.
- Ask before adding a dependency.

## API

- Error format is described in @docs/api-errors.md.
- One handler file per route in src/api/.

우선순위 및 병합

어떤 파일도 다른 파일을 덮어쓰지 않습니다. 검색된 파일을 모두 이어 붙입니다. 관리 정책을 먼저 불러온 다음 파일 시스템 루트부터 실행 디렉터리까지 순서대로 불러오므로, 더 가까운 파일이 나중에 읽힙니다. 같은 디렉터리에서는 CLAUDE.local.md가 CLAUDE.md 다음에 읽힙니다. 하위 디렉터리의 파일은 Claude가 해당 디렉터리의 파일을 읽을 때 필요에 따라 불러옵니다. claudeMdExcludes로 관리 정책을 제외할 수는 없습니다.

이 파일을 읽는 도구

팁

• CLAUDE.md를 사용하는 경우 첫 줄에 @AGENTS.md를 추가하세요. 그렇지 않으면 기본 설정에서 Claude Code가 AGENTS.md를 무시합니다.
• 영역별 지침은 .claude/rules/로 옮기고 paths frontmatter를 지정해 해당 파일에만 적용되도록 하세요.
• 가져오기 기능으로 파일을 정리할 수 있지만, 가져온 텍스트도 로드되므로 컨텍스트를 차지합니다.
• /doctor를 실행해 CLAUDE.md, CLAUDE.local.md, AGENTS.md, rules, skills를 한 번에 점검하세요.

기타 지침 파일