CLAUDE.md: 어디에 두고 어떻게 쓰는가

어디에 두면 누구에게 적용되나

작업 디렉터리와 그 상위 디렉터리의 CLAUDE.md·CLAUDE.local.md는 시작 시 로드됩니다. 하위 디렉터리의 것은 시작 시가 아니라 Claude가 그 디렉터리의 파일을 읽는 시점에 로드됩니다. 대규모 모노레포에서 다른 팀의 CLAUDE.md까지 딸려 온다면 설정 `claudeMdExcludes`에 글롭을 적어 제외할 수 있습니다.

무엇을 쓰고 무엇을 쓰지 않는가

공식이 제시한 기준은 명확합니다. "언젠가 또 설명하게 될 내용"을 쓰라는 것입니다. 구체적인 신호는 같은 실수를 두 번째로 했을 때, 코드 리뷰가 Claude가 알았어야 할 점을 지적했을 때, 지난 세션에 쳤던 정정을 또 쳤을 때, 새 팀원에게도 같은 설명이 필요할 때입니다.

• 쓸 것: 빌드·테스트 명령, 폴더 구조, 명명 규칙, "항상 X 한다" 유형의 규칙.
• 쓰지 않을 것: 여러 단계로 된 절차, 코드베이스의 일부에만 적용되는 이야기. 전자는 스킬로, 후자는 `.claude/rules/`의 경로 한정 규칙으로 옮깁니다.
• 구체적으로: "코드를 정리한다"가 아니라 "들여쓰기는 공백 2칸". "테스트한다"가 아니라 "커밋 전에 `npm test` 실행".
• 모순 없이: 두 파일이 반대되는 말을 하면 모델이 임의로 하나를 고를 수 있습니다.

@import로 나누기

`@path/to/file` 형식으로 다른 파일을 불러올 수 있습니다. 상대 경로는 작업 디렉터리가 아니라 그 import를 적은 파일 기준으로 해석되고, 불러온 파일이 또 불러올 수 있으며 최대 4단계입니다. 오해하기 쉬운 지점이 있는데, 불러온 파일도 시작 시 컨텍스트로 펼쳐지기 때문에 파일 분리는 정리를 위한 것이지 컨텍스트 절약이 되지는 않습니다.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

이미 AGENTS.md가 있다면

Claude Code가 읽는 것은 CLAUDE.md이지 AGENTS.md가 아닙니다. 다른 에이전트용으로 AGENTS.md를 운영 중인 저장소라면, CLAUDE.md를 만들고 `@AGENTS.md`로 불러오는 것이 공식 권장입니다. 이중 관리를 피하면서 그 아래에 Claude 전용 지시를 덧붙일 수 있습니다. Windows에서는 심볼릭 링크에 관리자 권한이나 개발자 모드가 필요하므로 import 방식이 안전합니다.

@AGENTS.md

## Claude Code

src/billing/ 아래 변경은 플랜 모드로 진행한다.

경로 한정 규칙으로 컨텍스트 아끼기

CLAUDE.md가 길어지면 주제를 `.claude/rules/`로 옮깁니다. YAML 프런트매터에 `paths`를 적은 규칙은 Claude가 해당 패턴에 맞는 파일을 읽을 때만 로드됩니다. `paths`가 없는 규칙은 무조건 로드되며 우선순위는 `.claude/CLAUDE.md`와 같습니다.

---
paths:
  - "src/api/**/*.ts"
---

# API 개발 규칙

- 모든 엔드포인트에서 입력 검증을 수행한다
- 오류 응답은 공통 포맷을 따른다