CLAUDE.md 잘 쓰는 법 — 세션마다 시니어 개발자를 고용하는 효과

Claude Code를 처음 쓰면 이런 일이 반복돼요.

세션 1: "우리 프로젝트는 TypeScript 씁니다"
세션 2: 또 "TypeScript 써요"
세션 3: 또또 "TypeScript요..."

Claude Code는 매 세션마다 기억을 초기화하고 시작해요.
아무것도 모르는 신입이 매일 아침 처음 출근하는 것과 같아요.

CLAUDE.md는 이걸 해결해요. 매 세션 시작 때 자동으로 읽히는 파일이에요.

---

CLAUDE.md가 뭔가

.
├── src/
├── package.json
└── CLAUDE.md    ← 여기

프로젝트 루트에 놓으면 Claude Code가 세션 시작마다 자동으로 읽어요.

신입 개발자에게 주는 온보딩 문서라고 생각하면 돼요. 단, 이 신입은 매일 아침 기억을 지우고 출근해요. 그래서 CLAUDE.md에 뭘 쓰느냐가 Claude Code 품질의 80%를 결정해요.

---

핵심 원칙 — 적게 쓸수록 더 잘 따른다

여기서 대부분 실수해요.

Claude Code 시스템 프롬프트가 쓰는 명령어 슬롯: ~50개
LLM이 안정적으로 따를 수 있는 지시 총량: 150~200개
CLAUDE.md에 쓸 수 있는 슬롯: 약 100~150개

→ CLAUDE.md가 길수록 전부 흐릿하게 따름
→ 짧을수록 핵심 규칙을 정확하게 따름

실제 실험 결과가 있어요. CLAUDE.md에 "항상 나를 Captain이라고 불러"를 넣으면 몇 메시지 후 Claude가 안 부르기 시작해요. 명령어가 많아질수록 전체 준수율이 균등하게 낮아지기 때문이에요.

목표: 200줄 이하. 2,000토큰 이하.

---

무엇을 써야 하나

1. 빌드/테스트/실행 커맨드

## 커맨드
- 개발 서버: `npm run dev`
- 테스트: `npm run test`
- 빌드: `npm run build`
- 린트: `npm run lint`
- 타입 체크: `npm run typecheck`

Claude가 코드 수정 후 테스트를 어떻게 실행해야 하는지 알아야 해요. 없으면 매번 물어보거나 틀린 커맨드를 써요.

2. 코드 스타일

## 코드 스타일
- TypeScript strict mode 사용
- CommonJS(require) 금지, ES modules(import/export) 사용
- 함수형 컴포넌트 + hooks 사용 (클래스 컴포넌트 금지)
- 상태 관리: Zustand (Redux 사용 금지)
- API 호출: React Query 사용

이걸 안 쓰면 Claude가 레거시 패턴으로 코드를 짜요. 특히 팀 프로젝트에서 일관성이 깨져요.

3. 아키텍처 핵심 정보

## 아키텍처
- 모노레포 구조: apps/web, apps/api, packages/shared
- 인증: NextAuth.js (apps/web/src/lib/auth.ts 참고)
- DB: PostgreSQL + Prisma ORM
- API: REST (GraphQL 아님)

## 핵심 파일 위치
- 라우팅: apps/web/src/app/
- DB 스키마: packages/db/schema.prisma
- 공통 타입: packages/shared/types/

100만 줄짜리 코드베이스에서 Claude가 인증 로직 찾으러 헤매지 않아요.

4. 절대 하면 안 되는 것

## 금지 사항
- main 브랜치 직접 push 금지
- .env 파일 수정 금지
- production DB 직접 쿼리 금지
- package.json 의존성 추가 시 반드시 확인 요청

이건 CLAUDE.md 지시사항이 70~80% 준수율인 거 알고 있죠? 그래서 절대 안 되는 것은 Hooks로 막아야 해요. CLAUDE.md는 가이드, Hooks는 강제예요.

5. 현재 작업 컨텍스트

## 현재 작업 (매주 업데이트)
- Sprint 목표: 결제 플로우 리팩토링
- 완료: 장바구니 UI 개선
- 진행 중: 토스페이먼츠 연동
- 블로커: PG사 웹훅 스펙 확인 필요

선택 사항이지만 있으면 Claude가 현재 맥락에 맞는 코드를 짜요.

---

무엇을 쓰면 안 되나

# 이런 거 넣으면 안됨

## 프로젝트 소개
이 프로젝트는 2023년에 시작된 e-commerce 플랫폼으로...
(Claude한테 회사 소개할 필요 없음)

## React란?
React는 Facebook이 만든 UI 라이브러리로...
(Claude가 React를 모름? 토큰 낭비)

## 전체 API 스펙
GET /api/users
POST /api/users
PUT /api/users/:id
... (200줄)
(별도 파일로 분리하고 경로만 적기)

---

Progressive Disclosure — 상세 정보는 별도 파일로

## 참고 문서
- 결제 시스템: docs/payment-architecture.md 참고
- 배포 프로세스: docs/deployment.md 참고
- API 컨벤션: docs/api-conventions.md 참고

이렇게 쓰면 Claude는 결제 관련 작업할 때만 payment-architecture.md를 읽어요. 매 세션마다 전부 읽지 않아도 돼요.

CLAUDE.md 직접 포함:
→ 매 요청마다 전부 토큰 소모

별도 파일 참조:
→ 필요할 때만 읽음
→ 토큰 절약 + 더 관련성 높은 컨텍스트

---

실전 CLAUDE.md 예시

# 프로젝트 컨텍스트

## 커맨드
- dev: `pnpm dev`
- test: `pnpm test`
- build: `pnpm build`
- lint+fix: `pnpm lint:fix`

## 스택
- Next.js 15 (App Router)
- TypeScript strict
- Tailwind CSS
- Supabase (Auth + DB)
- Zustand (클라이언트 상태)

## 코드 규칙
- ES modules만 사용 (require 금지)
- 서버 컴포넌트 기본, 필요할 때만 'use client'
- any 타입 사용 금지
- console.log 커밋 금지 (logger 사용)

## 구조
- 페이지: app/(routes)/
- 컴포넌트: components/
- 서버 액션: app/actions/
- DB 쿼리: lib/db/

## 참고 문서
- DB 스키마: lib/db/schema.ts
- 인증 로직: lib/auth/ 폴더
- 환경 변수: .env.example

## 금지
- main 직접 push 금지
- .env 수정 금지
- supabase 마이그레이션 자동 실행 금지

이게 전부예요. 짧고 명확해요.

---

/init으로 자동 생성 후 다듬기

# Claude Code가 자동으로 CLAUDE.md 초안 생성
> /init

코드베이스를 분석해서 빌드 시스템, 테스트 프레임워크, 디렉토리 구조를 자동으로 파악해요. 근데 보통 너무 길게 나와요. 자동 생성 후 필요 없는 내용 지우고 팀 규칙 추가하는 게 제일 빨라요.

---

CLAUDE.md vs Hooks — 역할 분리

CLAUDE.md:
→ 가이드라인 (70~80% 준수)
→ 코딩 스타일, 아키텍처, 참고 정보
→ "이렇게 하세요"

Hooks:
→ 강제 실행 (100% 준수)
→ 린트, 포맷팅, 보안 검사
→ "이건 반드시 일어납니다"

예시:
CLAUDE.md: "TypeScript strict 써주세요" → 대부분 따름
Hook: 파일 저장 시 tsc --noEmit 자동 실행 → 항상 실행

중요한 규칙은 CLAUDE.md에 쓰고, 절대적인 규칙은 Hook으로 강제해요.

---

팀 프로젝트에서 CLAUDE.md 관리

# Git으로 관리 (필수)
git add CLAUDE.md
git commit -m "docs: CLAUDE.md 결제 모듈 컨텍스트 추가"

# 팀원 모두 같은 CLAUDE.md 사용
# → 일관된 코드 품질
# → 온보딩 문서 역할도 함

신입 개발자가 들어왔을 때 CLAUDE.md 보여주면 프로젝트 파악하는 데도 도움돼요. 사람 온보딩 문서와 AI 온보딩 문서가 같아요.

---

 

📌 관련 글

Claude Code 4레이어 컨텍스트 시스템

매번 설명 반복하다 지쳤다면 — Claude Code 4레이어 컨텍스트 시스템

Claude Code 토큰 낭비 없애는 법

Claude Code 토큰 낭비 없애는 법 — 컨텍스트 관리 완전 가이드