CLAUDE.md는 무엇인가요?

프로젝트 루트에 두는 마크다운 파일로, Claude Code가 모든 세션에서 자동으로 컨텍스트로 로드합니다. 프로젝트 개요·구조·명령어·코드 컨벤션을 미리 알려주는 역할을 합니다.

프로젝트 단위는 루트의 `CLAUDE.md`, 사용자 전체는 `~/.claude/CLAUDE.md`에 둡니다. 두 파일이 모두 있으면 사용자 전역 → 프로젝트 순으로 로드되어 프로젝트 설정이 우선합니다.

어떤 내용을 포함해야 하나요?

프로젝트 개요, 기술 스택, 디렉토리 구조 요약, 자주 쓰는 명령어(build/dev/test), 코드 컨벤션, 절대 하지 말아야 할 것(금지 사항)을 포함합니다. 길면 길수록 좋은 것은 아니므로 핵심만 간결하게 작성합니다.

초안은 어떻게 만드나요?

Claude Code에서 `/init` 슬래시 커맨드를 실행하면 프로젝트를 분석해 초안을 자동 생성합니다. 초안을 검토·수정하는 방식이 가장 빠릅니다.

CLAUDE.md가 너무 길면 문제가 되나요?

매 세션 컨텍스트를 차지하므로 길어질수록 토큰 예산이 줄어듭니다. 한 화면에 들어가는 분량이 이상적이며, 세부 규칙은 별도 Skill로 분리하는 것을 권장합니다.

CLAUDE.md 잘 쓰는 법

CLAUDE.md가 왜 중요한가

Claude Code는 매 세션 시작 시 프로젝트 루트의 CLAUDE.md를 자동으로 컨텍스트에 로드합니다. 한 번 잘 작성하면 모든 세션에서 동일한 가이드가 적용되고, 매번 같은 설명을 반복할 필요가 없어집니다.

좋은 CLAUDE.md는 답변 품질을 즉시 개선하고 잘못된 가정·반복적인 실수를 줄입니다.

두 가지 위치

위치	적용 범위
`~/.claude/CLAUDE.md`	사용자 전역 (모든 프로젝트)
`<project>/CLAUDE.md`	해당 프로젝트만

두 파일이 모두 있으면 사용자 전역 → 프로젝트 순으로 로드되며, 프로젝트 설정이 더 구체적이라 우선 적용되는 효과가 있습니다.

초안 만들기

/init

Claude Code가 프로젝트 구조를 분석해 초안 CLAUDE.md를 생성합니다. 자동 초안을 검토·수정하는 방식이 가장 빠릅니다.

잘 쓰는 5가지 원칙

1. 짧고 구조적으로

매 세션 컨텍스트를 차지하므로 길수록 토큰 예산이 줄어듭니다. 한두 화면 분량이 이상적입니다.

2. “무엇이 있는지”보다 “어떻게 다루는지”

디렉토리 트리 전체를 적기보다 핵심 디렉토리의 역할과 자주 쓰는 명령어를 적습니다. Claude는 파일을 직접 탐색할 수 있으므로 모든 파일을 나열할 필요가 없습니다.

3. 금지 사항을 명시

긍정 지시보다 “하지 말 것” 목록이 효과가 큽니다.

## Rules
* Never commit or push without explicit user instruction
* Don't add error handling for impossible scenarios
* Don't introduce new dependencies without approval

4. 명령어를 코드 블록으로

build/dev/test 명령은 코드 블록에 넣어 Claude가 정확히 복사·실행할 수 있게 합니다.

## Commands
\```bash
npm run build       # 프로덕션 빌드
npm run dev         # 개발 서버 (포트 3030)
npm test            # 단위 테스트
\```

5. 자주 쓰는 워크플로 명시

콘텐츠 추가, 마이그레이션, 배포 등 반복 작업은 절차를 문서화합니다.

좋은 예시 구조

# 프로젝트 이름

## 개요
한 문단으로 무엇을 하는 프로젝트인지.

## 기술 스택
* Frontend: Next.js 15, Tailwind CSS
* Backend: Node.js, Prisma, PostgreSQL
* Hosting: Cloudflare Pages

## 명령어
\```bash
npm run dev
npm run build
npm test
\```

## 디렉토리 구조
* src/app — Next.js App Router 페이지
* src/components — UI 컴포넌트
* prisma/ — DB 스키마와 마이그레이션

## 코드 컨벤션
* 함수형 컴포넌트만 사용
* 상태 관리는 Zustand
* 테스트는 Vitest

## Rules
* 커밋·푸시는 사용자 명시 지시 시에만
* 새 라이브러리 추가 전 확인 요청

흔한 실수

❌ 디렉토리 트리 전체 복사 — Claude가 직접 탐색할 수 있음
❌ 한국어와 영어 혼용 — 한 언어로 일관되게
❌ 기능 설명 (이건 README의 역할)
❌ 너무 일반적인 베스트 프랙티스 (“코드는 가독성 있게”) — 프로젝트 고유 규칙만

세부 규칙은 Skill로 분리

CLAUDE.md가 길어지면 자주 쓰는 워크플로(콘텐츠 작성, 마이그레이션 절차 등)를 별도 Skill 파일로 분리합니다. CLAUDE.md에는 “어떤 작업 시 어떤 Skill을 호출하라”는 짧은 안내만 두면 됩니다.

다음 단계

Andrej Karpathy Skills — Karpathy 원칙을 담은 CLAUDE.md 템플릿 플러그인
Superpowers — CLAUDE.md와 함께 쓰면 워크플로 일관성이 더 강해짐
Skill 직접 만들기 — 분리된 규칙을 Skill로 작성하는 법