CLAUDE.md로 Claude Code 설정하기

Claude Code는 세션을 시작할 때 CLAUDE.md 파일을 읽어 프로젝트의 규칙과 맥락을 파악합니다. 잘 쓴 CLAUDE.md 하나가 매 세션 반복하던 설명을 없애 주지만, 잘못 쓰면 오히려 컨텍스트만 낭비합니다. 이 글에서는 계층 구조부터 작성 규칙, 안티패턴까지 정리합니다.

계층 구조와 로딩 순서

CLAUDE.md는 여러 위치에 둘 수 있고, 각 위치의 역할이 다릅니다.

위치	범위	용도
~/.claude/CLAUDE.md	사용자 전역	개인 선호 (언어, 스타일)
프로젝트 루트 CLAUDE.md	프로젝트 전체	빌드 명령, 아키텍처, 팀 규칙
하위 디렉터리 CLAUDE.md	해당 디렉터리	모듈별 특수 규칙
CLAUDE.local.md	개인 로컬 (git 제외)	개인 환경 전용 설정

전역과 프로젝트 루트 파일은 세션 시작 시 로드되고, 하위 디렉터리 파일은 그 경로의 파일을 다룰 때 반영됩니다. 규칙이 충돌하면 더 구체적인(가까운) 쪽이 우선한다고 생각하면 됩니다.

무엇을 넣어야 하는가

CLAUDE.md의 판단 기준은 하나입니다. "모델이 코드만 봐서는 알 수 없는데, 매 세션 필요한 정보인가?"

넣어야 할 것:

• 빌드·테스트·실행 명령 (pnpm test, make dev 등 정확한 명령)
• 코드베이스 구조의 요지 — 어느 디렉터리가 무엇인지 한 줄씩
• 팀 컨벤션 — 커밋 메시지 형식, 브랜치 전략, 스타일 규칙
• 하지 말아야 할 것 — "이 파일은 자동 생성이니 직접 수정 금지" 류

넣지 말아야 할 것:

• 코드를 읽으면 알 수 있는 내용 (함수 목록, API 시그니처)
• 한 번만 필요한 일회성 지시
• 장황한 프로젝트 소개 — 마케팅 문서가 아닙니다

잘 쓴 예시

# 프로젝트 규칙

## 명령어
- 개발 서버: `pnpm dev` (포트 3000)
- 테스트: `pnpm test` — 커밋 전 필수
- 타입 검사: `pnpm typecheck`

## 구조
- `src/app/` — Next.js App Router 페이지
- `src/lib/` — 순수 로직 (React 의존 금지)
- `src/data/` — 정적 데이터, 빌드 시 번들됨

## 규칙
- 커밋 메시지는 Conventional Commits (영문)
- `src/generated/` 는 자동 생성 — 직접 수정 금지

짧고, 명령이 정확하고, 금지 사항이 명시적입니다. 이 정도 분량이면 충분한 프로젝트가 대부분입니다.

흔한 안티패턴

1. 소설형 CLAUDE.md: 수천 단어짜리 문서는 매 세션 컨텍스트를 잡아먹습니다. 핵심 규칙만 남기고, 상세 문서는 별도 파일로 두고 경로만 안내하세요.
2. 철 지난 정보 방치: 옮겨진 디렉터리, 바뀐 명령어가 남아 있으면 모델이 확신을 갖고 틀립니다. 코드 리뷰 때 CLAUDE.md도 함께 갱신하는 습관이 필요합니다.
3. 강조 남발: 모든 항목에 "중요!", "반드시!"를 붙이면 실제 중요한 규칙이 묻힙니다. 강조는 어길 때 비용이 큰 규칙에만 아껴 쓰세요.
4. 개인 취향을 프로젝트 파일에: 개인 언어 선호나 로컬 경로는 전역 파일이나 CLAUDE.local.md로 분리해야 팀원과 충돌하지 않습니다.

유지보수 팁

CLAUDE.md는 한 번 쓰고 끝나는 문서가 아니라 코드와 함께 진화하는 설정입니다. 실전에서 잘 동작하는 루틴은 이렇습니다.

• 세션 중 모델이 같은 실수를 반복하면, 그 자리에서 규칙 한 줄을 추가합니다.
• 분기마다 한 번씩 전체를 읽고 죽은 규칙을 삭제합니다. 줄어드는 것이 좋은 신호입니다.
• 새 팀원 온보딩 문서와 겹치는 내용은 한쪽으로 통합하고 참조만 남깁니다.

결국 좋은 CLAUDE.md는 좋은 온보딩 문서와 같습니다. 새로 온 동료에게 "이것만 알면 바로 일할 수 있다"고 건넬 수 있는 분량과 정확도 — 그것이 기준입니다.