Claude Code는 세션을 열 때마다 빈 컨텍스트로 시작합니다. 어제 설명한 프로젝트 구조, 지난주에 정한 규칙, 절대 건드리면 안 되는 파일을 매번 다시 말해야 한다면 자동화라고 부르기 어렵습니다. CLAUDE.md는 그 반복을 없애는 파일입니다. 작업 폴더에 두면 Claude가 일을 시작하기 전에 반드시 읽고, 창을 껐다 켜도 같은 규칙으로 일합니다.
이 글은 「설정과 커스터마이즈」 코스의 첫 글입니다. CLAUDE.md가 있을 때 무엇이 달라지는지, /init으로 초안을 만들고 어떤 문장만 남길지, 얼마나 짧게 유지해야 하는지를 다룹니다. 다음 글 「settings.json 설정」에서는 CLAUDE.md가 못 하는 "강제"를 파일로 고정하는 방법을 이어서 봅니다.
핵심 요약
- CLAUDE.md는 매 세션 시작 시 컨텍스트에 통째로 실리는 마크다운 지침 파일입니다. 시스템 프롬프트가 아니라 사용자 메시지로 전달되므로 "부탁"이지 "강제"가 아닙니다.
/init으로 초안을 만들되, 코드베이스에서 유추할 수 있는 내용은 지우고 Claude가 스스로 알 수 없는 것만 남깁니다.- 공식 문서 기준 파일당 200줄 이하를 목표로 합니다. 길수록 컨텍스트를 먹고 준수율이 떨어집니다.
- 검증 가능한 문장만 적습니다. "잘 정리해라"가 아니라 "커밋 전에
pnpm test를 실행한다"처럼 씁니다. - 반드시 지켜야 하는 것은 CLAUDE.md가 아니라 훅과 퍼미션으로 겁니다.
CLAUDE.md가 있으면 무엇이 달라지나
우리 초급 과정 2주차에서 수강생이 처음 만드는 CLAUDE.md는 딱 3줄입니다.
1. 나는 정책자금 컨설턴트다. 모든 문서는 존댓말로 쓴다.
2. 고객 실명은 절대 문서에 그대로 쓰지 않는다. (홍OO 형태로)
3. 확실하지 않은 수치는 지어내지 말고 "확인 필요"라고 표시한다.
이 3줄이 있는 폴더와 없는 폴더에서 같은 요청("상담 기록을 보고서로 정리해줘")을 던지면 결과가 갈립니다. 없는 쪽은 반말과 존댓말이 섞이고 고객 이름이 그대로 들어갑니다. 있는 쪽은 첫 응답부터 규칙을 따릅니다. 요청 문장을 매번 길게 쓰는 대신 규칙을 파일로 고정한 것, 이것이 "프롬프트가 아니라 시스템"으로 가는 첫걸음입니다.
기술적으로는 이렇습니다. Claude Code는 현재 작업 디렉터리에서 상위로 올라가며 CLAUDE.md를 찾아 전부 읽고, 시스템 프롬프트 다음의 첫 사용자 메시지처럼 컨텍스트에 붙입니다. 그래서 Claude는 이 내용을 "설정"이 아니라 "맥락"으로 취급합니다. 잘 따르지만 보장은 없습니다. 이 성질을 알아야 뒤에서 설명할 "무엇을 적고 무엇을 훅으로 뺄지"가 결정됩니다.
/init 으로 초안 만들기
프로젝트 루트에서 Claude Code를 켜고 /init을 입력하면 Claude가 코드베이스를 훑고 빌드 명령, 테스트 방법, 폴더 구조를 담은 CLAUDE.md 초안을 만듭니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선안을 제안합니다. 저장소에 AGENTS.md나 .cursorrules 같은 다른 도구용 설정이 있으면 그것도 읽어 반영합니다.
cd ~/Developer/my-project # Windows: cd %USERPROFILE%\Developer\my-project
claude
/init
초안은 출발점일 뿐입니다. /init이 만든 내용의 상당 부분은 Claude가 매 세션 다시 파악할 수 있는 것(디렉터리 목록, 의존성 목록)이라 그대로 두면 낭비입니다. 다음 절의 기준으로 걸러냅니다.
무엇을 적고 무엇을 빼야 하나
공식 문서는 "다시 설명해야 할 것을 적는 장소"로 CLAUDE.md를 정의합니다. 우리는 이것을 네 가지 질문으로 바꿔 씁니다.
적을 것:
- Claude가 같은 실수를 두 번째로 했을 때 그 교정 내용
- 코드만 봐서는 알 수 없는 결정과 이유(왜 이 테이블은 건드리면 안 되는지)
- 매 세션 필요한 명령(빌드·테스트·실행 포트)
- 새 팀원에게도 똑같이 알려줘야 하는 규칙
뺄 것:
- 폴더 트리, 의존성 목록처럼 Claude가 파일을 읽으면 아는 것
- 다단계 절차(배포 순서 12단계 같은 것). 이것은 Skill로 분리합니다.
- 특정 파일 종류에서만 쓰는 규칙.
.claude/rules/에paths를 걸어 분리합니다. - 비밀값. API 키, 토큰, 비밀번호는 어떤 형태로도 적지 않습니다.
.env에 두고.gitignore에 올립니다.
우리 사이트 레포의 CLAUDE.md를 예로 들면 "가격·환불의 단일 소스는 lib/courses.ts, refundPolicy 없는 과정은 주문 API가 거부한다. 이 게이트를 우회하지 않는다"는 남깁니다. 코드를 읽어도 그 게이트가 "일부러" 있다는 사실은 알 수 없기 때문입니다. 반면 "app 폴더에 라우트가 있다"는 지웁니다.
기본 구조 예시
4주차 교재의 템플릿을 조금 다듬은 형태입니다. 헤더와 불릿으로 묶어야 Claude가 사람처럼 훑어 읽습니다.
# 프로젝트 작업 규칙
## 목적
정책자금 컨설팅 상담 기록을 보고서로 자동 변환하는 프로젝트.
## 실행
- 개발 서버: `pnpm dev` (포트 4400)
- 검증: `pnpm build && pnpm test`
## 규칙
1. 민감 정보는 코드에 직접 쓰지 않는다. 키는 `.env`로 관리한다.
2. 고객 실명은 홍OO 형태로만 쓴다.
3. 수정 전에 기존 구조를 먼저 읽고, 큰 변경은 요약을 남긴다.
4. main 브랜치에 직접 작업하지 않는다.
## 주의
- `data/customers.csv`는 원본이다. 읽기만 하고 수정하지 않는다.
동작을 바꾸는 문장 vs 그렇지 않은 문장
같은 뜻이라도 검증할 수 있게 쓴 문장만 효과가 있습니다.
| 효과가 약한 문장 | 동작을 바꾸는 문장 |
|---|---|
| 코드를 깔끔하게 유지한다 | 들여쓰기는 2칸, 세미콜론 생략 |
| 변경 후 테스트한다 | 커밋 전에 pnpm test를 실행하고 실패하면 커밋하지 않는다 |
| 보고서는 보기 좋게 | 보고서 섹션 순서는 요약 → 원인 → 조치 → 다음 액션 |
| 위험한 건 하지 마라 | supabase/schema.sql은 add column if not exists로만 누적한다 |
두 규칙이 서로 모순되면 Claude는 임의로 하나를 고릅니다. 사용자 홈의 CLAUDE.md와 프로젝트 CLAUDE.md가 서로 다른 들여쓰기를 요구하는 상황이 흔한 예입니다. 주기적으로 두 파일을 나란히 놓고 충돌을 지웁니다.
짧게 유지해야 하는 이유
CLAUDE.md는 길이에 상관없이 전부 로드됩니다. 자동 메모리(MEMORY.md)는 처음 200줄 또는 25KB까지만 실리지만 CLAUDE.md에는 그런 상한이 없습니다. 즉 길게 쓰면 쓴 만큼 매 세션 토큰을 내고, 공식 문서도 "더 짧은 파일이 더 나은 준수를 만든다"고 명시합니다. 목표는 파일당 200줄 이하입니다.
우리 레포에서 지키는 관례는 "CLAUDE.md에는 규칙과 참조만, 상세는 분리"입니다. 스키마 설명이나 운영 절차는 별도 문서에 두고 CLAUDE.md에는 경로만 적습니다. 참고로 @경로 가져오기는 조직에는 도움이 되지만 가져온 파일도 시작 시 로드되므로 컨텍스트 절약은 되지 않습니다. 절약이 목적이면 .claude/rules/의 경로 조건부 규칙을 씁니다.
/doctor를 실행하면 체크인된 CLAUDE.md에서 코드베이스로 유추 가능한 내용을 찾아 정리를 제안합니다(Claude Code v2.1.206 이상).
어디에 두나: 계층 구조
CLAUDE.md는 네 범위에 둘 수 있고, 넓은 범위부터 순서대로 전부 읽혀 이어 붙습니다. 덮어쓰기가 아니라 연결입니다.
| 범위 | 위치 | 공유 |
|---|---|---|
| 조직 정책 | macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md |
조직 전체 |
| 사용자 | ~/.claude/CLAUDE.md |
나만, 모든 프로젝트 |
| 프로젝트 | ./CLAUDE.md 또는 ./.claude/CLAUDE.md |
팀(git) |
| 로컬 | ./CLAUDE.local.md |
나만, 이 프로젝트 |
4주차 교재의 폴더 구조 그대로 루트 CLAUDE.md는 전체 공통 규칙, frontend/CLAUDE.md는 화면 전용 규칙, backend/CLAUDE.md는 API·DB 전용 규칙으로 나눕니다. 하위 폴더의 파일은 시작 시 읽지 않고 Claude가 그 폴더의 파일을 읽을 때 함께 로드됩니다. 자세한 배치 패턴은 「CLAUDE.md 배치 장소와 우선순위」에서 다룹니다.
점검 주기
- Claude가 같은 실수를 반복한 날: 그 자리에서 한 줄 추가합니다.
- 기능 하나가 끝났을 때: 새 규칙·새 명령이 생겼으면 반영하고, 더 이상 맞지 않는 줄을 지웁니다.
- 월 1회:
/context의 Memory files 목록으로 로드된 파일과 토큰 비중을 확인합니다. CLAUDE.md가 컨텍스트의 큰 몫을 차지하면 분리 대상입니다.
정리
- CLAUDE.md는 매 세션 실리는 지침이며 강제 장치가 아닙니다. 강제는 훅과 퍼미션의 몫입니다.
/init으로 시작하되 코드에서 유추 가능한 내용은 지우고, 검증 가능한 문장만 남깁니다.- 200줄 이하를 목표로 하고, 절차는 Skill로, 파일별 규칙은
.claude/rules/로 분리합니다. - 비밀값은 어떤 형태로도 적지 않습니다.
자주 묻는 질문
CLAUDE.md는 어디에 두고 어떻게 만드나요?
프로젝트 루트에 CLAUDE.md(또는 .claude/CLAUDE.md)를 두고 git에 커밋하면 팀 전체에 적용됩니다. 개인 취향은 ~/.claude/CLAUDE.md, 이 프로젝트에서만 쓰는 개인 설정은 CLAUDE.local.md에 둡니다. 처음이라면 프로젝트 루트에서 /init을 실행해 초안을 받은 뒤 다듬는 것이 가장 빠릅니다.
CLAUDE.md에 무엇을 적어야 하나요?
매 세션 다시 설명하게 되는 것만 적습니다. 실행·테스트 명령, 코드만 봐서는 알 수 없는 결정과 그 이유, 반복된 실수의 교정, 건드리면 안 되는 파일. 반대로 폴더 트리와 의존성 목록처럼 Claude가 읽으면 아는 내용, 그리고 비밀값은 뺍니다.
적어 두었는데 Claude가 지키지 않는 이유는 무엇인가요?
먼저 /context의 Memory files 목록에서 그 파일이 실제 로드됐는지 확인합니다. 목록에 없으면 위치가 틀린 것입니다. 로드됐는데도 안 지키면 문장이 모호하거나 다른 CLAUDE.md와 충돌하는 경우가 대부분입니다. "커밋 전 반드시 테스트"처럼 특정 시점에 꼭 실행돼야 하는 것은 CLAUDE.md가 아니라 훅으로 옮깁니다.
CLAUDE.md는 얼마나 길어도 되나요?
기술적 상한은 없지만 공식 권장은 파일당 200줄 이하입니다. 넘어가면 토큰을 더 쓰고 준수율이 떨어집니다. 길어지면 파일별 규칙은 .claude/rules/로, 절차는 Skill로 옮깁니다.
개인 설정과 팀 설정은 어떻게 나누나요?
팀 규칙은 프로젝트 CLAUDE.md에 커밋하고, 내 로컬 포트나 테스트 계정 같은 개인 값은 CLAUDE.local.md에 씁니다. CLAUDE.local.md는 자동으로 무시되지 않으므로 .gitignore에 직접 추가해야 합니다. 환경 변수 CLAUDE_CODE_NEW_INIT=1을 켠 상태에서 /init의 개인 옵션을 고르면 이 추가를 대신해 줍니다.