CLAUDE.md 최적화: AI를 위한 인수인계 문서이자 헌법 (프로젝트 메모리)
CLAUDE.md는 단순한 메모장이 아니다. 매번 세션이 시작될 때마다 고용되는 '시니어 AI 개발자'에게 건네는 인수인계서이자, 프로젝트의 헌법이다.
1. 핵심 개념: "매 세션마다 고용되는 시니어 개발자를 위한 인수인계서"
정의: CLAUDE.md는 Claude Code가 세션을 시작할 때마다 가장 먼저, 그리고 자동으로 읽어들이는 파일이다. AI에게 프로젝트의 문맥, 규칙, 아키텍처를 주입하는 "시스템 프롬프트"의 확장판 역할을 한다.
왜 최적화해야 하는가? (The Cost of Memory)
- 토큰 세금: 이 파일은 모든 세션의 시작점에 로드된다. 파일이 크면 클수록 작업을 시작하기도 전에 기본 토큰 비용(Overhead)이 발생한다.
- 주의력 분산 (Instruction Drift): 내용이 너무 길거나(300줄 이상) 불필요한 정보가 많으면, AI가 핵심 규칙을 무시하거나 "환각(Hallucination)"을 일으킬 확률이 높아진다. Anthropic 분석 결과, 너무 많은 지침은 모델 성능을 저하시킬 수 있다.
- 속도 저하: 불필요한 컨텍스트 로딩은 초기 응답 속도(Time to First Token)를 늦춘다.
2. 메모리 계층 구조 (The Hierarchy of Context)
CLAUDE.md 하나에 모든 것을 다 넣으려 하지 마라. 계층적 구조(Tiered Architecture)를 사용하여 토큰 효율성과 유지보수성을 동시에 잡아야 한다. 설정은 상위에서 하위로 상속/병합된다.
| 계층 (Priority) | 파일 위치 | 역할 및 포함 내용 | 권장 토큰량 |
|---|---|---|---|
| 1. Global (User) | ~/.claude/CLAUDE.md | 개인적 선호도: "항상 한국어로 답해", "리팩토링 시 주석 달지 마", 개인 API 키 관리 방식 등 모든 프로젝트에 적용될 규칙. | < 300 토큰 |
| 2. Project (Root) | ./CLAUDE.md | 팀 공통 규칙: 기술 스택(버전 포함), 아키텍처 패턴(Clean Arch 등), 핵심 빌드/테스트 명령어, 코드 스타일. | < 1,000 토큰 |
| 3. Subsystem | ./src/auth/CLAUDE.md | 모듈별 특수 규칙: 특정 폴더(예: 인증 모듈) 내에서만 유효한 로직이나 컨벤션. Claude Code가 해당 디렉토리에서 작업할 때만 로드됨. | 500~1,500 토큰 |
| 4. Reference | ./docs/*.md | 상세 문서: 절대 CLAUDE.md에 내용을 직접 넣지 않고, @docs/api.md 형태로 참조(Pointer)만 함. | 0 (필요시 로드) |
Tip (AGENTS.md 표준): 최근 업계에서는
CLAUDE.md대신AGENTS.md를 사용하여 Cursor, Copilot, Windsurf 등 다양한 AI 도구가 공유할 수 있는 표준 설정 파일을 만드는 추세다.ln -s AGENTS.md CLAUDE.md로 심볼릭 링크를 걸어 호환성을 확보하자.
3. 최적화 전략 A: 진보적 공개 (Progressive Disclosure)
모든 정보를 한 번에 주입하는 것이 아니라, "지도가 어디에 있는지"만 알려주는 전략이다.
- Bad Pattern (Monolithic):
CLAUDE.md안에 500줄짜리 데이터베이스 스키마와 API 명세서를 전부 적어넣는 것. (토큰 낭비, 주의력 저하) - Good Pattern (Pointer System):
## Documentation Map
- Authentication logic: See @src/auth/README.md
- Database Schema: See @docs/schema.sql
- API Endpoints: See @src/api/routes.ts
이 방식을 사용하면 Claude Code는 평소에는 가벼운 상태를 유지하다가, 인증 관련 질문을 받을 때만 스스로 @src/auth/README.md를 읽어(Read Tool) 문맥을 확장한다.
4. 최적화 전략 B: "Linter의 일을 AI에게 시키지 마라"
가장 흔한 실수는 CLAUDE.md를 "비싼 Linter"로 쓰는 것이다.
- 제거 대상: "들여쓰기는 스페이스 2칸", "세미콜론 필수", "변수명은 camelCase" 같은 스타일 규칙.
- 이유: 이런 규칙은
ESLint,Prettier,.editorconfig가 훨씬 빠르고 정확하게 처리한다. AI에게 이런 걸 시키면 토큰만 낭비하고, 정작 중요한 아키텍처 규칙을 까먹게 만든다. - 대체 문구: "Code style follows standard ESLint config. Run
npm run lintto verify." 한 줄이면 충분하다.
5. 작성 프레임워크: WHAT - WHY - HOW
Anthropic이 권장하고 전문가들이 사용하는 구조적 작성법이다.
- WHAT (기술 스택 & 구조):
- "Node.js v20, TypeScript, Prisma ORM 사용."
- "src/core는 비즈니스 로직, src/adapters는 외부 연동."
- WHY (설계 철학 & 의도):
- "우리는 클린 아키텍처를 따르므로 도메인 레이어는 외부 라이브러리에 의존해선 안 됨."
- "성능보다 가독성을 우선함."
- HOW (워크플로우 & 명령어):
- "테스트는
npm test로 실행." - "DB 마이그레이션은
npx prisma migrate dev사용." - 중요: "자주 실수하는 부분(Gotchas)"을 기록해두면 디버깅 시간을 획기적으로 줄일 수 있다(예: "이 모듈은 순환 참조 문제가 있으니 주의").
- "테스트는
6. 실전 운영 팁 (Maintenance)
#명령어로 라이브 업데이트: 작업을 하다가 Claude Code가 뭔가를 잘 수행했거나 새로운 규칙을 발견하면, 터미널에서# 항상 테스트 코드를 먼저 작성해라고 입력하라. Claude Code가 즉시 이 내용을 메모리에 추가하거나 파일에 기록한다.- 주기적 가지치기 (Pruning): 프로젝트가 진행됨에 따라
CLAUDE.md는 비대해질 수 있다. 정기적으로 내용을 검토하여 이미 AI가 잘 알고 있는 내용이나 더 이상 쓰지 않는 레거시 규칙은 과감히 삭제하라. - 동적 헤더 활용:
CLAUDE.md대신 스크립트를 훅(Hook)으로 연결하여 현재 Git 브랜치 이름이나 최근 커밋 로그 같은 동적인 정보를 프롬프트에 주입하는 것도 고급 전략 중 하나다.
📝 샘플 템플릿 (Copy & Paste)
[이상적인 Root CLAUDE.md 예시 (100줄 미만)]
# Project Context
## Tech Stack
- Next.js 14 (App Router), TypeScript, TailwindCSS
- State: Zustand
- DB: Supabase (PostgreSQL)
## Architecture Rules
- **Layered Arch**: UI Components -> Features -> Services -> API
- Never import server-only code in client components.
- Use `@/` alias for imports.
## Key Commands
- Start: `pnpm dev`
- Test: `pnpm test` (Run related tests only)
- Lint: `pnpm lint --fix`
## Documentation Map (Read on demand)
- API Specs: @docs/api-v1.md
- Auth Flow: @docs/auth-diagram.mermaid
- DB Schema: @prisma/schema.prisma
## Workflow
1. Create a plan before coding complex features.
2. Verify changes with `pnpm test`.
3. Keep commits atomic and use Conventional Commits.
