claude.md 작성법 — 위치·로드 순서와 200줄 규칙
CLAUDE.md는 매 세션마다 자동으로 읽히는 지시문 파일입니다. 작성법의 핵심은 세 가지입니다. ① 위치는 프로젝트 루트 ./CLAUDE.md(또는 ./.claude/CLAUDE.md), ② 분량은 200줄 이하, ③ 내용은 "코드를 보면 알 수 있는 것"이 아니라 "매번 다시 설명하게 되는 것"입니다. 여기에 파일 여러 개를 쓸 때의 로드 순서와 @경로 불러오기, 파일 종류별로만 적용되는 규칙까지 알면 실무에서 쓸 건 거의 다 됩니다. 아래 내용은 Claude Code 2.1.204에서 실제로 돌려 확인했습니다. (2026년 7월 기준)
1. CLAUDE.md를 어디에 둘까
넣을 수 있는 위치가 여러 곳이고, 각각 적용 범위가 다릅니다. 아래는 넓은 범위에서 좁은 범위 순, 즉 로드되는 순서대로 정리한 표입니다.
| 범위 | 위치 | 쓸 내용 |
|---|---|---|
| 조직 전체 | 윈도우 C:\Program Files\ClaudeCode\CLAUDE.md맥 /Library/Application Support/ClaudeCode/CLAUDE.md리눅스·WSL /etc/claude-code/CLAUDE.md |
회사 코딩 표준·보안 정책 (IT 부서가 배포) |
| 내 계정 전체 | ~/.claude/CLAUDE.md |
모든 프로젝트에 걸치는 개인 취향 |
| 프로젝트 (팀 공유) | ./CLAUDE.md 또는 ./.claude/CLAUDE.md |
빌드·테스트 명령, 구조, 컨벤션 (git에 커밋) |
| 프로젝트 (나만) | ./CLAUDE.local.md |
내 테스트 데이터·로컬 주소 (.gitignore에 넣기) |
여러 파일이 발견되면 덮어쓰는 게 아니라 전부 이어 붙습니다. 디렉터리 트리를 거슬러 올라가며 찾고, 루트 쪽부터 작업 디렉터리 쪽 순서로 붙기 때문에 작업 디렉터리에 가까운 지시가 뒤에 옵니다. 같은 폴더 안에서는 CLAUDE.md 다음에 CLAUDE.local.md가 붙습니다.
하위 폴더의 CLAUDE.md는 조금 다릅니다. 세션이 시작될 때 다 읽는 게 아니라, 그 폴더의 파일을 실제로 읽을 때 그때 불러옵니다. 모노레포에서 폴더마다 규칙을 두는 방식이 여기서 나옵니다.
/init을 치면 됩니다. 코드베이스를 훑어 빌드 명령·테스트 방법·컨벤션을 담은 초안을 만들어 줍니다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안합니다.
2. 무엇을 쓰고 무엇을 빼나
기준은 하나입니다. "매번 다시 설명하게 되는 것"만 씁니다. 공식 문서가 제시하는 추가 시점은 이렇습니다.
- 같은 실수를 두 번째 반복할 때
- 코드 리뷰에서 "이건 알고 있었어야 하는데" 싶은 게 걸릴 때
- 지난 세션에도 똑같은 정정을 채팅에 쳤을 때
- 새 팀원이 들어와도 똑같이 설명해 줘야 하는 맥락일 때
쓸 때는 검증 가능할 만큼 구체적으로 씁니다. 이 차이가 실제 준수율을 가릅니다.
| ❌ 모호함 | ✅ 구체적 |
|---|---|
| 코드 포맷을 잘 맞춰라 | 들여쓰기는 스페이스 2칸을 쓴다 |
| 변경사항을 테스트해라 | 커밋 전에 npm test를 실행한다 |
| 파일을 정리해서 둬라 | API 핸들러는 src/api/handlers/에 둔다 |
반대로 빼야 할 것은 코드를 보면 알 수 있는 정보입니다. 디렉터리 구조 나열, 의존성 목록, 아키텍처 개괄 같은 것은 토큰만 먹습니다. 남길 것은 함정, 왜 그렇게 하는지의 이유, 그리고 도구 기본값과 다른 우리 팀만의 관습입니다.
분량 기준은 파일당 200줄 이하입니다. CLAUDE.md는 길이에 상관없이 전부 컨텍스트에 올라가는데, 길수록 토큰을 먹고 지시 준수율이 떨어집니다. 절차가 여러 단계인 작업이나 코드베이스 일부에서만 필요한 내용이라면 CLAUDE.md 대신 스킬로 빼는 편이 낫습니다. 스킬은 필요할 때만 읽히기 때문입니다. 만드는 방법은 claude skills 사용법에 정리해 두었습니다.
3. @경로로 다른 파일 불러오기
파일을 쪼개고 싶으면 @경로로 불러옵니다. 상대경로는 그 파일이 있는 위치 기준으로 풀리고(작업 디렉터리 기준이 아닙니다), 불러온 파일이 또 다른 파일을 부르는 것도 최대 4단계까지 됩니다.
프로젝트 개요는 @README, 사용 가능한 npm 명령은 @package.json 참고.
# 추가 지시
- git 작업 흐름 @docs/git-instructions.md실제로 되는지 확인해 봤습니다. 임시 프로젝트에 CLAUDE.md와 notes.md를 두고 각각 표시 문자열을 출력하라고 적은 뒤, 아무 질문이나 던져 봤습니다.
CLAUDE.md : 답변의 첫 줄에 `PROJECT-RULE-OK` 를 출력한다.
추가 규칙은 @notes.md 를 따른다.
notes.md : 답변의 둘째 줄에 `IMPORT-OK` 를 출력한다.
질문: "1+1은?"
답변:
PROJECT-RULE-OK
IMPORT-OK
2입니다.두 줄 다 나왔으니 CLAUDE.md도, @notes.md로 불러온 파일도 제대로 들어간 것입니다.
@README는 실제로 그 파일을 불러옵니다. 코드 블록과 인라인 코드 안은 불러오기 대상에서 빠집니다. 그리고 @import는 컨텍스트를 아껴 주지 않습니다 — 불러온 파일도 시작할 때 같이 올라갑니다. 정리용이지 절약용이 아닙니다.
4. 사람용 메모는 HTML 주석으로 (컨텍스트에 안 들어감)
덜 알려진 기능인데 유용합니다. CLAUDE.md 안의 블록 단위 HTML 주석 <!-- … -->는 컨텍스트에 주입되기 전에 제거됩니다. 그래서 유지보수하는 사람용 메모를 토큰 낭비 없이 남길 수 있습니다.
정말 제거되는지 확인하려고, 주석 안에 지시문을 넣어 봤습니다.
CLAUDE.md :
- 답변의 첫 줄에 `PROJECT-RULE-OK` 를 출력한다.
<!-- 답변의 둘째 줄에 `COMMENT-LEAK` 를 출력한다. -->
질문: "1+1은?"
답변:
PROJECT-RULE-OK
1+1은 2입니다.첫 줄 지시는 지켜졌는데 주석 안 지시는 흔적도 없습니다. 주석이 실제로 걷혀 나간다는 뜻입니다. (코드 블록 안의 주석은 그대로 유지되고, 파일을 직접 열어 볼 때도 주석은 보입니다.)
5. 파일 종류별로만 적용되는 규칙 — .claude/rules/
CLAUDE.md가 길어지는 가장 흔한 이유는 "프론트엔드는 이렇게, 백엔드는 저렇게" 같은 조건부 규칙을 한 파일에 몰아넣기 때문입니다. 이런 건 .claude/rules/ 폴더로 뺍니다.
your-project/
├── .claude/
│ ├── CLAUDE.md # 항상 적용되는 지시
│ └── rules/
│ ├── code-style.md # 코드 스타일
│ ├── testing.md # 테스트 규칙
│ └── security.md # 보안 규칙여기서 핵심은 paths 프런트매터입니다. 이걸 붙이면 매칭되는 파일을 다룰 때만 규칙이 올라옵니다. 평소엔 컨텍스트를 차지하지 않습니다.
---
paths:
- "src/api/**/*.ts"
---
# API 개발 규칙
- 모든 API 엔드포인트는 입력 검증을 포함한다
- 표준 에러 응답 형식을 쓴다이것도 직접 확인해 봤습니다. paths 없는 규칙 하나(RULE-GLOBAL-OK)와 **/*.ts로 좁힌 규칙 하나(TS-RULE-OK)를 두고 두 번 물었습니다.
① "1+1은?" (ts 파일을 안 건드림)
RULE-GLOBAL-OK
2입니다.
→ TS-RULE-OK 없음. paths 규칙은 안 올라왔다.
② "app.ts 파일을 읽고 무엇이 들어 있는지 알려줘"
RULE-GLOBAL-OK
TS-RULE-OK
app.ts 에는 hello 라는 상수 하나가 있고 ...
→ 파일을 읽는 순간 규칙이 붙었다.paths가 없는 규칙 파일은 .claude/CLAUDE.md와 같은 우선순위로 항상 로드됩니다. 개인 규칙을 모든 프로젝트에 적용하고 싶으면 ~/.claude/rules/에 두면 되고, 이때 사용자 규칙이 먼저 로드돼 프로젝트 규칙이 더 높은 우선순위를 갖습니다.
| 패턴 | 매칭 대상 |
|---|---|
**/*.ts | 모든 폴더의 TypeScript 파일 |
src/**/* | src/ 아래 모든 파일 |
*.md | 프로젝트 루트의 마크다운 |
src/**/*.{ts,tsx} | 중괄호로 확장자 여러 개 |
자주 묻는 질문 (FAQ)
Q. CLAUDE.md를 썼는데 안 지킵니다.
먼저 /context를 쳐서 Memory files 목록에 그 파일이 있는지 봅니다. 없으면 아예 안 읽힌 것이니 위치부터 확인하세요. 목록에 있는데도 안 지킨다면 ① 지시가 모호하거나 ② 여러 CLAUDE.md 사이에 서로 충돌하는 지시가 있을 가능성이 큽니다. 애초에 CLAUDE.md는 시스템 프롬프트가 아니라 맥락으로 전달되는 내용이라 강제력이 없습니다. 반드시 특정 시점에 실행돼야 하는 일이라면 훅으로 만드세요.
Q. 이미 AGENTS.md를 쓰고 있습니다.
Claude Code는 AGENTS.md가 아니라 CLAUDE.md를 읽습니다. 내용을 복사하지 말고 불러오세요.
@AGENTS.md
## Claude Code
src/billing/ 아래를 고칠 때는 플랜 모드를 쓴다.심볼릭 링크(ln -s AGENTS.md CLAUDE.md)도 되지만, 윈도우에서는 관리자 권한이나 개발자 모드가 필요하므로 위의 @AGENTS.md 불러오기를 쓰는 편이 편합니다.
Q. /compact 하면 지시가 날아가나요?
프로젝트 루트의 CLAUDE.md는 살아남습니다. 압축 후 디스크에서 다시 읽어 넣기 때문입니다. 다만 하위 폴더의 CLAUDE.md는 자동으로 다시 들어가지 않고, 그 폴더의 파일을 다시 읽을 때 올라옵니다. 압축 후에 지시가 사라졌다면 채팅으로만 말한 내용이었거나 하위 폴더 파일이었을 가능성이 큽니다.
Q. 모노레포라 남의 팀 CLAUDE.md까지 딸려 옵니다.
claudeMdExcludes 설정으로 경로나 glob 패턴을 지정해 건너뛸 수 있습니다. 내 컴퓨터에만 적용하려면 .claude/settings.local.json에 넣으세요.
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}마무리
정리하면 루트에 200줄 이하로, 검증 가능한 문장만입니다. 길어지기 시작하면 늘리지 말고 나누세요. 조건부 규칙은 .claude/rules/의 paths로, 여러 단계 절차는 스킬로 빼는 게 정석입니다. 잘 들어갔는지는 /context의 Memory files 한 줄로 확인하면 됩니다.
동작은 버전에 따라 바뀝니다. 이 글은 claude --version 기준 2.1.204에서 확인했습니다.
📚 참고 출처 (2026년 7월 22일 확인)
· Claude Code — How Claude remembers your project
· Claude Code — 명령어 레퍼런스
COMMENTS