CLAUDE.md 작성법: 프로젝트 규칙을 한 페이지로
CLAUDE.md는 세션마다 읽히는 규칙 파일입니다. 어디에 두고, /init으로 시작해, 200줄 아래로 유지하며, 구체적으로 쓰는 법을 공식 문서 기준으로 정리했습니다.
CLAUDE.md는 Claude Code가 세션을 시작할 때마다 읽는 프로젝트 규칙 파일입니다. 2026년 9월 11일 기준 공식 메모리 문서는 "다시 설명해야 할 것을 적어 두는 자리"라고 정의합니다. 빌드 명령, 폴더 구조, "항상 X를 하라"는 규칙처럼 매 세션에 필요한 사실만 넣고, 200줄 아래로 유지하는 것이 핵심입니다.
왜 한 페이지인가
Claude Code의 대화는 세션마다 새로 시작됩니다. 지난 세션에서 "테스트는 npm test로 돌려"라고 말했어도 다음 세션의 Claude는 모릅니다. CLAUDE.md는 그 간극을 메우는 문서이고, 세션이 열릴 때 컨텍스트 창에 그대로 실립니다. 그래서 길수록 토큰을 먹고, 공식 문서 표현대로 "긴 파일은 준수율을 떨어뜨립니다."
문서가 제안하는 추가 시점은 네 가지입니다.
- Claude가 같은 실수를 두 번째 했을 때
- 코드 리뷰에서 "이 코드베이스에선 원래 이렇게 한다"가 나왔을 때
- 지난 세션에 쳤던 정정을 이번 세션에 또 치고 있을 때
- 새 팀원에게도 똑같이 설명해야 할 내용일 때
어디에 두는가
| 범위 | 위치 | 용도 | 공유 대상 |
|---|---|---|---|
| 조직 정책 | macOS /Library/Application Support/ClaudeCode/CLAUDE.md 등 | 회사 표준·보안 규정 | 기기의 모든 사용자 |
| 개인 전체 | ~/.claude/CLAUDE.md | 내 코딩 취향, 도구 단축 | 나(모든 프로젝트) |
| 프로젝트 | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | 아키텍처·컨벤션·워크플로 | 팀(버전 관리) |
| 프로젝트 개인 | ./CLAUDE.local.md | 내 샌드박스 URL, 테스트 데이터 | 나(이 프로젝트) — .gitignore에 추가 |
현재 디렉터리와 그 위 디렉터리의 파일이 모두 로드되고, 하위 디렉터리의 CLAUDE.md는 Claude가 그 폴더의 파일을 읽을 때 따라 들어옵니다. 로드됐는지 확인하려면 세션에서 /context를 치고 Memory files 목록을 봅니다.
시작은 /init
빈 파일에서 시작하지 않아도 됩니다. /init을 실행하면 Claude가 코드베이스를 분석해 빌드 명령·테스트 방법·컨벤션이 담긴 초안을 만듭니다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안합니다. 초안이 나오면 Claude가 스스로 알아낼 수 없는 것만 덧붙입니다. 예를 들어 "결제 코드는 반드시 plan 모드로 먼저 계획한다" 같은 팀 규칙입니다.
잘 읽히는 지시문 세 가지 원칙
공식 문서의 예를 그대로 옮기면 이렇습니다.
| 모호함 | 구체적 |
|---|---|
| "코드 포맷을 잘 맞춰라" | "2칸 들여쓰기를 쓴다" |
| "변경은 테스트해라" | "커밋 전에 npm test를 실행한다" |
| "파일을 정리해라" | "API 핸들러는 src/api/handlers/에 둔다" |
- 구체성: 검증 가능한 문장으로 씁니다.
- 구조: 마크다운 헤더와 불릿으로 묶습니다. Claude도 사람처럼 구조를 훑습니다.
- 일관성: 두 규칙이 충돌하면 Claude가 임의로 하나를 고를 수 있습니다. 상위 폴더 CLAUDE.md, 하위 폴더 파일,
.claude/rules/까지 주기적으로 모순을 정리합니다.
비개발자를 위한 최소 템플릿
강의나 블로그 초안, 자동화 스크립트처럼 코드가 많지 않은 프로젝트라면 이 정도로 충분합니다.
# 이 프로젝트
- 목적: 주간 뉴스레터 초안을 만드는 폴더
- 글은 `drafts/`에, 완성본은 `published/`에 둔다
- 문체: 존댓말, 한 문장 30자 안팎, 영어 약어는 처음 나올 때 풀어 쓴다
- 외부 사실은 반드시 출처 URL을 같은 줄에 적는다
# 하지 말 것
- `published/` 안의 파일은 수정하지 않는다
- 이메일·전화번호 같은 개인정보를 예시로 만들지 않는다
파일이 커지기 시작하면 세 가지로 나눕니다. 특정 폴더에만 해당하는 규칙은 .claude/rules/ 아래 파일로 옮기고 paths 프런트매터로 범위를 제한합니다. 여러 단계 절차는 스킬로 뺍니다. 다른 문서를 그대로 끌어오고 싶으면 @docs/git-instructions.md처럼 @경로 임포트를 씁니다. 단, 임포트한 파일도 세션 시작 시 함께 로드되므로 컨텍스트 절약 효과는 없습니다.
자주 하는 실수
- AGENTS.md만 있고 CLAUDE.md가 없다. Claude Code는
CLAUDE.md만 읽습니다.@AGENTS.md한 줄짜리 CLAUDE.md를 만들어 두 도구가 같은 규칙을 보게 합니다. - 지켜지지 않는 규칙을 계속 늘린다. CLAUDE.md는 안내이지 강제가 아닙니다. "커밋 전 반드시 lint"처럼 특정 시점에 꼭 실행돼야 하는 것은 훅으로 옮깁니다.
- HTML 주석에 메모를 남기며 토큰을 걱정한다.
<!-- -->블록 주석은 컨텍스트에 들어가기 전에 제거됩니다. 유지보수 메모는 마음껏 남겨도 됩니다. /compact뒤에 규칙이 사라진 것 같다. 프로젝트 루트 CLAUDE.md는 압축 후 다시 읽힙니다. 사라진 것은 대화 중에만 말했던 지시입니다. 그런 지시는 파일로 옮깁니다.
자동 메모리와의 차이
같은 문서는 auto memory도 설명합니다. Claude가 사용자의 정정과 선호를 스스로 ~/.claude/projects/<project>/memory/에 적어 두는 기능이고 기본값이 켜져 있습니다. CLAUDE.md는 사람이 쓰는 규칙, auto memory는 Claude가 쓰는 학습 노트입니다. "항상 pnpm을 써"처럼 기억하라고 말하면 auto memory로 가고, 규칙 파일에 넣고 싶으면 "CLAUDE.md에 추가해"라고 말하거나 /memory로 직접 엽니다.