CLAUDE.md 작성법

CLAUDE.md는 클로드 코드에게 주는 "이 프로젝트의 안내서"입니다. 클로드 코드는 작업을 시작할 때 이 파일을 읽어, 프로젝트의 목적·기술 스택·규칙·자주 하는 실수 등을 미리 파악합니다. 잘 작성된 CLAUDE.md는 매번 같은 설명을 반복하지 않아도 클로드가 일관되게 작업하도록 만듭니다.

1. /init으로 생성하기

프로젝트가 어느 정도 자리 잡았을 때 /init 명령을 실행하면, 클로드 코드가 현재 프로젝트를 분석해 CLAUDE.md 초안을 자동으로 만들어줍니다.

/init

언제 /init을 해야 할까?

빈 폴더에서 바로 /init을 하면 분석할 파일이 없어 의미 있는 내용이 생성되지 않습니다. 또한 프로젝트 초반에는 구조가 자주 바뀌므로, 어느 정도 형태가 잡힌 뒤 생성하는 것을 권합니다. 너무 일찍 만든 CLAUDE.md는 오래된 정보로 오히려 클로드를 헷갈리게 할 수 있습니다.

2. CLAUDE.md에 무엇을 담을까

CLAUDE.md에는 클로드가 알아야 할 프로젝트 정보를 담습니다. 다음 항목이 특히 유용합니다.

항목	예시
프로젝트 개요	"한국어 교육용 정적 웹사이트, 바닐라 JS"
기술 스택	사용 언어, 프레임워크, 라이브러리
프로젝트 구조	주요 폴더/파일의 역할
개발 명령어	실행/빌드/테스트/린트 명령
코딩 스타일	네이밍 규칙, 포맷팅 규칙
자주 하는 실수	"이 함수는 직접 호출 금지, 반드시 X를 거칠 것"

아래는 정적 웹사이트 프로젝트에서 생성된 CLAUDE.md 예시입니다.

# CLAUDE.md

이 파일은 이 저장소에서 작업할 때 Claude Code에 대한 가이드를 제공합니다.

## 프로젝트 개요
바닐라 HTML, CSS, JavaScript로 만든 한국어 교육용 단일 페이지 웹사이트입니다.

## 프로젝트 구조
- `index.html` - 홈/소개/커리큘럼 섹션을 포함하는 메인 파일
- `styles.css` - 반응형 디자인, 애니메이션 등 전체 스타일
- `script.js` - 부드러운 스크롤, 모바일 네비게이션 등 상호작용

## 개발 명령어
빌드 프로세스 없음. 로컬 서버로 확인:
- `python -m http.server` 또는 `npx serve`

## 스타일링 규칙
- 색상은 CSS 변수로 관리
- BEM 유사 클래스 네이밍
- 768px 브레이크포인트 기준 모바일 우선 반응형

3. /memory로 수정하기

프로젝트가 진행되면서 클로드가 기억해야 할 내용이 바뀝니다. /memory 명령으로 CLAUDE.md를 빠르게 열어 수정할 수 있습니다.

/memory

특히 터미널만 사용하는 분에게 편리합니다. 물론 VSCode에서 직접 CLAUDE.md 파일을 열어 수정해도 됩니다.

4. CLAUDE.md를 "살아있는 문서"로 만들기

가장 강력한 활용법은, 클로드가 실수할 때마다 그 내용을 CLAUDE.md에 추가하는 것입니다.

이렇게 하면 지식이 일회성으로 사라지지 않고 누적되는 자산이 됩니다. 팀이라면 CLAUDE.md를 Git에 커밋해 공유하세요. 팀원 모두가 같은 규칙을 클로드에게 전달할 수 있습니다.

주의: CLAUDE.md가 만능은 아닙니다.

CLAUDE.md에 "반드시 지켜라"라고 적어도 클로드가 가끔 무시하거나 어기는 경우가 있습니다. 핵심 규칙은 짧고 명확하게, 정말 중요한 것 위주로 적으세요. 내용이 너무 길고 장황하면 오히려 잘 지켜지지 않습니다. 중요한 작업은 결과를 직접 검증하는 습관(10장)이 필요합니다.

5. CLAUDE.md의 위치

CLAUDE.md는 보통 프로젝트 루트에 둡니다. 이외에도 적용 범위에 따라 위치를 나눌 수 있습니다.

프로젝트 CLAUDE.md: 프로젝트 루트. 해당 프로젝트에만 적용.
사용자 전역 메모리: ~/.claude/ 경로. 모든 프로젝트에 공통 적용.
하위 폴더 CLAUDE.md: 특정 하위 폴더에만 적용되는 세부 규칙.

다음 장에서는 클로드 코드의 답변 품질을 좌우하는 컨텍스트와 토큰 관리를 다룹니다.