Claude Code를 본격적으로 쓰기 시작하면 누구나 한 번쯤 만나는 파일이 있습니다. 바로 CLAUDE.md입니다. 이름은 자주 들었지만 정확히 어디에 두어야 하는지, 어떤 내용을 써야 효과가 있는지 헷갈려서 그냥 비워 두시는 분이 많습니다. 그러나 이 파일을 잘 갖춰 두면 매번 같은 설명을 반복할 필요가 없어지고, AI의 답변 일관성도 눈에 띄게 좋아집니다. 위치, 용도, 잘 쓰는 법까지 한 번에 정리해 드립니다.
목차
CLAUDE.md는 어떤 파일인가
CLAUDE.md는 Claude Code가 세션을 시작할 때 자동으로 읽어 들이는 마크다운 형식의 지침서입니다. 일종의 “프로젝트 영구 메모리” 역할을 하며, 매 대화마다 같은 컨텍스트를 다시 입력할 필요를 없애 줍니다. 빌드 명령, 코드 스타일, 금지 사항, 워크플로우 같은 정보를 한 곳에 모아 두면, 새 세션을 열 때마다 Claude가 처음부터 그 규칙을 알고 시작합니다.
중요한 점은 README와 다르다는 것입니다. README는 사람이 읽는 문서이고, CLAUDE.md는 AI가 읽는 문서입니다. 따라서 사람을 위한 친절한 설명보다는, AI가 의사결정을 내릴 때 필요한 짧고 단호한 규칙 위주로 작성하는 것이 효과적입니다. 자세한 공식 문서는 Claude Code 메모리 문서에서 확인하실 수 있습니다.
CLAUDE.md 파일 위치 4가지
Claude Code는 한 곳이 아니라 여러 위치의 CLAUDE.md를 동시에 읽습니다. 위치마다 적용 범위가 다르므로 용도에 맞춰 사용하시면 됩니다.
| 위치 | 경로 | 적용 범위 | 주된 용도 |
|---|---|---|---|
| 프로젝트 메모리 | ./CLAUDE.md | 해당 저장소 전체 | 팀 공유 규칙, Git 커밋 |
| 사용자 메모리 | ~/.claude/CLAUDE.md | 모든 프로젝트 | 개인 선호, 공통 명령 단축 |
| 하위 디렉터리 | ./하위폴더/CLAUDE.md | 해당 폴더 작업 시 | 모노레포 내 패키지별 규칙 |
| 로컬 오버라이드 | ./CLAUDE.local.md | 본인 머신만 | (현재는 @imports 권장) |
여러 CLAUDE.md가 동시에 존재하면 Claude Code가 모두 합쳐서 컨텍스트로 사용합니다. 충돌이 있으면 작업 중인 위치에 더 가까운 파일이 우선합니다. 즉 모노레포에서 패키지 폴더 안의 CLAUDE.md가 루트보다 우선 적용됩니다. 팀 공유가 필요한 규칙은 반드시 프로젝트 루트의 CLAUDE.md에 두고 Git에 커밋하시는 것을 권해 드립니다.
어떤 내용을 써야 효과가 있을까
아무거나 다 적는다고 좋은 것은 아닙니다. Claude가 코드를 보면 알 수 있는 정보, 일반적인 언어 관례는 굳이 적지 않습니다. 대신 “Claude가 추측할 수 없는 정보”에 집중하셔야 합니다.
꼭 포함하면 좋은 항목
- 빌드·테스트 명령:
npm test,pytest -k smoke처럼 프로젝트 고유의 실행 명령 - 프로젝트 특수 코드 스타일: “ES 모듈만 사용, CommonJS 금지”, “함수는 50줄 이내” 같은 명시적 규칙
- 금지 사항·보안 규칙:
.env수정 금지, 운영 DB 직접 쿼리 금지, 외부 API 호출 시 절대 키 노출 금지 - 아키텍처 한 줄 설명: API 핸들러는
src/api/, 모델은src/models/, 마이그레이션은db/migrations/ - 워크플로우: 커밋 전 lint·타입체크 실행, PR 전 단일 테스트 통과 확인
- 네이밍 규칙: 브랜치
feat/*,fix/*, 함수는 동사로 시작 - 외부 문서 링크: 사내 위키, 공식 API 문서 URL (본문 전체 복붙 대신 링크만)
구체적인 작성 예
나쁜 예와 좋은 예를 비교해 보시면 차이가 분명합니다.
| 나쁜 예 | 좋은 예 |
|---|---|
| 좋은 코드를 작성하세요 | 2칸 들여쓰기, import는 알파벳 순 정렬 |
| 테스트하세요 | 커밋 전 npm test 실행, 모든 테스트 통과 필수 |
| 파일을 정리하세요 | API 핸들러는 src/api/handlers/에 둡니다 |
| 예쁘게 만드세요 | 버튼 색은 토큰 변수 –color-brand만 사용 |
피해야 할 안티패턴
의외로 흔하게 보이는 잘못된 사용법입니다. 적은 만큼 컨텍스트를 잡아먹기 때문에, 빼는 것도 중요합니다.
- 모호한 추상적 지시: “잘 짜세요”, “최선을 다하세요”는 무시될 가능성이 높습니다.
- Claude가 이미 아는 일반 규칙: “JavaScript는 세미콜론을 씁니다” 같은 보편 지식은 불필요합니다.
- API 문서 전체 복사: 토큰만 낭비됩니다. 공식 URL 링크로 대체하시는 것이 낫습니다.
- 자주 바뀌는 정보: 진행 중 이슈, 임시 결정 사항은 별도 파일이나 PR 본문에 두는 편이 안전합니다.
- 각 파일 상세 설명: Claude는 파일을 직접 읽을 수 있으므로 전체 아키텍처만 짧게 요약하면 충분합니다.
- Claude를 린터로 사용: “스타일 검사를 매번 해 줘” 같은 요청은 비용이 큽니다. ESLint, Biome 같은 자동 도구에 맡기시는 것이 합리적입니다.
분량과 모듈화: 짧을수록 잘 지킨다
CLAUDE.md는 200~300줄 이내가 일반적인 권장선입니다. 너무 길면 컨텍스트를 차지하고, 역설적으로 Claude의 규칙 준수율이 떨어집니다. 분량이 많아질 것 같으면 @imports 문법으로 모듈화하시는 것이 좋습니다. 메인 파일은 짧게 두고, 세부 규칙은 별도 마크다운으로 빼서 필요할 때만 불러오는 방식입니다.
예를 들어 다음과 같이 폴더를 구성하실 수 있습니다.
./CLAUDE.md— 핵심 규칙과 다른 파일에 대한 import./.claude/rules/code-style.md— 상세 코드 스타일./.claude/rules/testing.md— 테스트 컨벤션./.claude/rules/security.md— 보안 요구사항
메인 CLAUDE.md 안에서는 @.claude/rules/code-style.md처럼 경로를 적어 주면 Claude가 필요 시점에 해당 파일까지 읽어 옵니다.
처음 만들 때는 /init 명령부터
빈 파일을 마주 보고 시작하기 어려우시면 Claude Code의 /init 명령을 활용하시면 됩니다. 현재 프로젝트 구조를 분석해서 기본 골격을 자동으로 만들어 줍니다. 그 결과물을 토대로 본인 프로젝트의 특수한 규칙을 추가하거나 불필요한 부분을 제거하시면 됩니다. 처음부터 완벽할 필요는 없으며, Claude가 반복적으로 헷갈리는 지점이 보일 때마다 한 줄씩 추가해 나가는 식의 점진적 개선이 가장 현실적입니다.
자주 묻는 질문
CLAUDE.md를 안 만들면 어떻게 되나요?
Claude Code는 정상 동작하지만, 매 세션마다 프로젝트 컨텍스트를 처음부터 추측하게 됩니다. 같은 설명을 반복해야 하고, 답변 일관성도 떨어집니다. 짧게라도 만들어 두시는 편이 효율적입니다.
프로젝트용과 개인용을 같이 둬도 되나요?
네, 권장되는 방식입니다. 팀과 공유할 규칙은 ./CLAUDE.md에 두고 Git에 커밋, 본인만의 단축 명령이나 선호도는 ~/.claude/CLAUDE.md에 따로 두시면 두 파일이 자연스럽게 합쳐져 적용됩니다.
CLAUDE.local.md는 이제 쓰면 안 되나요?
금지된 것은 아니지만 공식적으로는 @imports 사용을 권장합니다. 본인만 보는 메모는 별도 파일에 두고 메인 CLAUDE.md에서 import 처리하시는 편이 유지보수하기 쉽습니다.
CLAUDE.md는 누가 더 잘 관리해 주나요?
Claude 본인에게 직접 시키실 수 있습니다. “이번 세션에서 반복적으로 헷갈렸던 규칙을 CLAUDE.md에 정리해 줘”라고 부탁하시면 적절한 위치에 항목을 추가해 줍니다. 다만 추가된 내용은 사람이 한 번 검토하고 커밋하시는 것이 안전합니다.
정리
CLAUDE.md는 프로젝트 루트와 홈 디렉터리 두 곳을 기본으로 두시고, 모노레포라면 하위 폴더에도 추가하시면 됩니다. 내용은 “Claude가 추측할 수 없는 것” 위주로, 빌드 명령·코드 스타일·금지 사항·워크플로우를 짧고 구체적으로 적으시는 것이 핵심입니다. 200줄을 넘어가면 모듈화하고, 처음부터 완벽을 노리기보다 실수가 보일 때마다 한 줄씩 보강해 나가시는 것이 가장 효과적입니다. 작은 파일 하나로 매일의 AI 협업 품질이 달라집니다.