CLAUDE.md 작성법: Claude Code 결과물을 바꾸는 한 파일

핵심 요약: CLAUDE.md는 Claude Code가 매 세션 자동으로 읽는 프로젝트 사용 설명서입니다(Cursor의 Rules에 해당). /init으로 초안을 만들 수 있지만, 품질을 가르는 건 그 이후의 편집입니다. 원칙은 하나: 짧게 유지하세요. 너무 길면 중요한 규칙이 소음에 묻혀 무시됩니다. 항상 필요한 규칙만 남기고, 가끔 쓰는 지침은 스킬로, 반드시 지켜져야 하는 것은 훅으로 옮기는 것이 2026년 기준 정석입니다.

이 글에서 다루는 내용: CLAUDE.md의 역할, /init 활용, 꼭 들어가야 할 내용, 길어졌을 때의 다이어트법, 실전 예시.

CLAUDE.md는 무엇을 하나

프로젝트 루트의 CLAUDE.md는 세션 시작 시 항상 컨텍스트에 로드됩니다. 빌드·테스트 명령, 코드 관례, 아키텍처 요약, 금지 사항을 여기에 적어두면 매번 설명할 필요가 없어집니다. 홈 디렉터리(~/.claude/CLAUDE.md)에 두면 모든 프로젝트에 적용되는 개인 규칙이 됩니다 — Cursor의 Project Rules / User Rules 구분과 같은 구조입니다(Cursor Rules 글 참고).

시작: /init으로 초안 생성

프로젝트에서 /init을 실행하면 코드베이스를 분석해 초안을 만들어줍니다. 초안은 출발점일 뿐입니다. 실제 가치는 "문서에 없는 팀의 암묵지"를 추가할 때 나옵니다: 어떤 테스트 명령을 쓰는지, 어떤 폴더는 건드리면 안 되는지, 커밋은 누가 하는지.

꼭 들어가야 할 5가지

# 명령어: 빌드/테스트/린트 실행 방법 (make test, pytest 등)
# 스택: 언어·프레임워크 버전 (Django 5.x, Python 3.12)
# 관례: 코드 스타일 중 도구가 어기기 쉬운 것만
# 금지: 마이그레이션 직접 실행 금지, main 직접 커밋 금지 등
# 구조: 핵심 디렉터리의 역할 한 줄씩

반대로 넣지 말아야 할 것: 일반적인 코딩 상식("깨끗한 코드를 작성하라"), 도구가 이미 잘 지키는 규칙, 가끔만 필요한 긴 절차. 이런 것이 쌓이는 순간 정말 중요한 "금지" 항목의 준수율이 떨어집니다.

길어졌다면: 다이어트 3단계

① 삭제 — Claude가 이미 잘 하는 지시는 지웁니다. 한 달 써보면 어떤 줄이 무의미한지 보입니다. ② 스킬로 이동 — "마이그레이션 절차", "릴리스 체크리스트"처럼 특정 상황에만 필요한 플레이북은 스킬로 빼면 호출될 때만 로드되어 평소 컨텍스트를 아낍니다. ③ 훅으로 이동 — "수정 후 린트 실행" 같은 규칙은 프롬프트가 아니라 훅(이벤트 시 자동 실행되는 스크립트)으로 만들면 100% 확실하게 실행됩니다. 스킬·훅 활용은 별도 글에서 다룹니다.

제가 쓰는 실제 구성 (Django 프로젝트)

제 CLAUDE.md는 30줄이 안 됩니다. 명령어 5줄(test/lint/run), 스택 2줄, 금지 4줄(마이그레이션 실행 금지, .env 접근 금지, main 커밋 금지, 의존성 추가 시 사유 설명), 관례 5줄(서비스 레이어, select_related, pytest 스타일), 구조 요약 몇 줄. 처음에는 100줄이 넘었는데, 지켜지지 않는 규칙이 늘어나는 걸 보고 절반 이상 지웠더니 오히려 준수율이 올라갔습니다. Cursor Rules에서 배운 교훈("Always 규칙은 짧게")이 여기서도 그대로 통했습니다.

자주 묻는 질문 (FAQ)

Q. CLAUDE.md와 Cursor의 .cursor/rules를 둘 다 관리해야 하나요?

A. 두 도구를 함께 쓴다면 그렇습니다. 내용이 겹치므로 한쪽을 원본으로 정하고 다른 쪽을 요약 유지하는 방식이 현실적입니다. 핵심 금지 사항은 반드시 양쪽에 두세요.

Q. git에 커밋해야 하나요?

A. 네, 프로젝트 CLAUDE.md는 커밋해서 팀과 공유하는 것이 표준입니다. 개인 취향은 홈 디렉터리의 전역 CLAUDE.md에 두세요.

Q. 하위 폴더에도 CLAUDE.md를 둘 수 있나요?

A. 네. 모노레포처럼 영역별 규칙이 다른 경우 하위 디렉터리에 별도 CLAUDE.md를 두면 해당 영역 작업 시 함께 참조됩니다.

한눈에 보는 요약

CLAUDE.md는 "항상 로드되는 짧은 계약서"입니다. 명령어·스택·금지·핵심 관례만 남기고, 플레이북은 스킬로, 강제 사항은 훅으로. 같은 걸 세 번 설명하고 있다면 CLAUDE.md에 넣고, CLAUDE.md가 화면을 넘어가면 다이어트할 시간입니다.

함께 보면 좋은 글

Claude Code 완전 정리 (2026년 기준)
Claude Code 서브에이전트·훅·스킬 활용법
Cursor Rules 설정 방법 (대응 개념)

참고 자료

Claude Code 공식 베스트 프랙티스
Steering Claude Code (Anthropic 공식 블로그)