클로드 코드는 세션이 끝나면 대화 내용을 잊습니다. 그런데 매번 "우리 프로젝트는 TypeScript를 쓰고, 테스트는 npm test로 돌리고, 한국어 주석을 달아 줘"라고 반복하는 것은 번거롭습니다. 이 문제를 해결하는 것이 CLAUDE.md 파일입니다.
CLAUDE.md는 프로젝트 폴더 맨 위(루트)에 두는 텍스트 파일로, 클로드 코드가 세션을 시작할 때마다 자동으로 읽습니다. 새로 온 직원 책상에 놓아두는 '업무 매뉴얼'이라고 생각하면 됩니다. 한 번 잘 써 두면 모든 세션에서 효과를 봅니다.
가장 쉬운 시작: /init
CLAUDE.md 자동 생성
# 프로젝트 폴더에서 클로드 코드 실행 후 입력
/init
# 클로드가 프로젝트를 분석해서 CLAUDE.md 초안을 만들어 줍니다.
# 초안을 검토하고 나만의 규칙을 추가하세요.무엇을 적어야 하나요?
- 자주 쓰는 명령어: 빌드, 테스트, 실행 방법 (클로드가 추측하다 틀리는 것을 방지)
- 코드 스타일 규칙: 들여쓰기, 네이밍, 사용하는 라이브러리
- 프로젝트 구조: 중요한 폴더가 어디에 있고 무슨 역할인지
- 하지 말아야 할 것: 건드리면 안 되는 파일, 금지된 패턴
- 우리 팀의 언어: 커밋 메시지나 주석을 한국어로 쓸지 등
실제 예시 파일
CLAUDE.md 예시
# 프로젝트: 우리 동네 맛집 지도
## 기술 스택
- React + TypeScript + Vite
- 스타일: Tailwind CSS
- DB: Supabase
## 자주 쓰는 명령어
- 개발 서버: npm run dev
- 테스트: npm test
- 타입 체크: npx tsc --noEmit
## 코드 규칙
- 컴포넌트는 함수형으로, 파일 하나에 컴포넌트 하나
- any 타입 사용 금지
- 주석과 커밋 메시지는 한국어로 작성
## 주의사항
- src/legacy/ 폴더는 수정하지 말 것
- DB 스키마 변경은 반드시 나에게 먼저 물어볼 것위치에 따른 종류
| 위치 | 적용 범위 | 용도 |
|---|---|---|
| 프로젝트 루트의 CLAUDE.md | 이 프로젝트에서만 | 팀 공용 규칙 (Git으로 공유 가능) |
| ~/.claude/CLAUDE.md | 내 컴퓨터의 모든 프로젝트 | 개인 취향 (말투, 개인 습관) |
| 하위 폴더의 CLAUDE.md | 해당 폴더 작업 시 추가로 적용 | 특정 모듈만의 세부 규칙 |
대화 중 클로드가 좋은 규칙을 어겼거나 새 규칙을 정했다면, 그 자리에서 "방금 정한 규칙을 CLAUDE.md에 추가해 줘"라고 말하세요. 입력창에서 #으로 시작하는 메시지를 보내 기억에 바로 추가하는 방법도 있습니다.
CLAUDE.md는 짧을수록 강합니다. 규칙이 수백 줄이면 클로드가 중요한 것을 놓치고, 컨텍스트도 낭비됩니다. '이걸 어기면 실제로 문제가 되는가?'를 기준으로 꼭 필요한 것만 남기고 주기적으로 다이어트하세요.
CLAUDE.md를 잘 가꾸는 것은 클로드 코드를 '나만의 개발자'로 키우는 과정입니다. 실수를 발견할 때마다 규칙을 한 줄씩 추가하면, 클로드는 갈수록 우리 팀처럼 일하게 됩니다.