CLAUDE.md 제대로 쓰는 법 — Claude Code 생산성을 두 배로 올리는 파일

Claude Code 쓰면서 처음에 제일 답답했던 게 뭐냐면, 매번 같은 말을 반복해야 한다는 거였다. "들여쓰기는 2칸으로 해줘", "패키지 매니저는 pnpm 쓰고 있어", "CSS는 Tailwind만 써", "console.log 남기지 마"... 세션 새로 열 때마다 이걸 다시 설명하고 있는 나를 발견했다.

그러다 CLAUDE.md를 알게 됐고, 이게 게임 체인저였다. 한 시간 투자해서 제대로 써두니까 그 뒤로 같은 설명을 반복할 일이 없어졌다. 어떤 글에서 "CLAUDE.md는 투자 대비 효과(ROI)가 가장 높은 작업"이라고 했는데, 정말 공감한다.

오늘은 이 CLAUDE.md를 어떻게 쓰는지, 어떻게 써야 효과가 있는지 정리해보려고 한다.

---

CLAUDE.md가 뭔데

한 줄로 말하면, Claude Code가 세션 시작할 때마다 자동으로 읽는 프로젝트 설명서다.

Claude Code는 매번 새로운 세션으로 시작한다. 사람처럼 "어제 우리가 뭘 했더라" 하고 기억하지 못한다. 그래서 매번 프로젝트의 맥락을 알려줘야 하는데, CLAUDE.md에 한 번 써두면 세션이 시작될 때 Claude가 자동으로 이 파일을 읽고 작업을 시작한다.

쉽게 비유하면, 신입 개발자가 입사할 때 받는 온보딩 문서 같은 거다. "우리 팀은 이런 컨벤션을 쓰고, 이런 도구를 쓰고, 이런 건 하면 안 된다"를 정리해둔 문서. Claude한테 매 세션마다 이 문서를 쥐어주는 셈이다.

---

메모리 계층 구조 — CLAUDE.md는 한 곳에만 있는 게 아니다

이게 처음에 잘 모르고 넘어가는 부분인데, CLAUDE.md는 여러 위치에 둘 수 있고 각각 역할이 다르다. Claude Code가 세션을 시작하면 여러 위치의 파일을 모아서 합쳐 읽는다.

3가지 주요 위치

1. 글로벌 (~/.claude/CLAUDE.md)
   → 내 모든 프로젝트에 적용
   → 개인 코딩 스타일, 자주 쓰는 단축어 등

2. 프로젝트 (./CLAUDE.md)
   → 해당 프로젝트에만 적용
   → 가장 많이 쓰는 위치. Git에 커밋해서 팀과 공유.

3. 로컬/개인 (.claude/CLAUDE.md 또는 하위 디렉토리)
   → 프로젝트 안에서 개인적인 설정
   → Git에 커밋 안 함 (.gitignore에 추가)

우선순위

같은 지시사항이 여러 위치에 있으면 더 구체적인(specific) 것이 우선한다.

구체적 ← → 일반적
개인 > 프로젝트 > 글로벌

예를 들어:

• 글로벌 파일: "들여쓰기는 2칸"
• 프로젝트 파일: "들여쓰기는 4칸"

→ 이 프로젝트에서는 4칸이 적용된다. 프로젝트가 글로벌보다 구체적이니까.

디렉토리 트리 탐색

Claude Code는 현재 작업 디렉토리에서 시작해서 상위로 올라가며 CLAUDE.md를 찾는다. 모노레포 같은 구조에서 유용하다.

my-monorepo/
├── CLAUDE.md              ← 전체 공통 규칙
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md      ← 프론트엔드 전용 규칙
│   └── backend/
│       └── CLAUDE.md      ← 백엔드 전용 규칙

packages/frontend/에서 작업하면 루트의 CLAUDE.md + 프론트엔드 CLAUDE.md가 같이 적용된다. 현재 위치에 가까운 파일일수록 더 큰 영향을 준다.

---

CLAUDE.md 만들기

방법 1: 직접 만들기

프로젝트 루트에 CLAUDE.md 파일을 만들고 내용을 쓰면 된다.

touch CLAUDE.md

방법 2: /init 명령어

Claude Code 세션에서 /init을 실행하면 Claude가 프로젝트를 분석해서 CLAUDE.md 초안을 만들어준다.

/init

이러면 프로젝트의 기술 스택, 디렉토리 구조, 빌드 명령어 같은 걸 자동으로 파악해서 기본 틀을 만들어준다. 여기서 시작해서 다듬는 게 편하다.

방법 3: # 키로 즉석 추가

세션 중에 # 키를 누르고 지시사항을 입력하면 자동으로 CLAUDE.md에 저장된다. 작업하다가 "아, 이건 기억해뒀으면 좋겠다" 싶을 때 흐름 안 끊고 바로 추가할 수 있다.

# 항상 함수에 JSDoc 주석을 달아줘

---

잘 쓴 CLAUDE.md 예시

내가 실제로 쓰는 구조다. 그대로 가져다 수정해서 써도 된다.

# 프로젝트 개요

이 프로젝트는 Next.js 14 기반 SaaS 대시보드입니다.
사용자가 구독을 관리하고 사용량을 추적하는 서비스입니다.

## 기술 스택

- 프레임워크: Next.js 14 (App Router)
- 언어: TypeScript (strict mode)
- 스타일링: Tailwind CSS
- DB: PostgreSQL + Prisma
- 인증: NextAuth.js
- 패키지 매니저: pnpm
- 테스트: Vitest + Testing Library
- 배포: Vercel

## 명령어

- 개발 서버: `pnpm dev`
- 빌드: `pnpm build`
- 테스트: `pnpm test`
- 테스트(watch): `pnpm test:watch`
- 린트: `pnpm lint`
- 타입 체크: `pnpm typecheck`
- DB 마이그레이션: `pnpm prisma migrate dev`

## 코딩 컨벤션

- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- 컴포넌트 파일명: PascalCase (예: UserCard.tsx)
- 유틸 함수 파일명: camelCase (예: formatDate.ts)
- 들여쓰기: 2칸
- 세미콜론 사용
- import는 절대 경로 사용 (@/components/...)

## 아키텍처 규칙

- API 라우트는 src/app/api/ 아래에 위치
- 비즈니스 로직은 src/services/에 분리
- DB 접근은 반드시 src/lib/db.ts의 Prisma 클라이언트 통해서만
- API 응답 형식: { success: boolean, data?: T, error?: string }
- 클라이언트 컴포넌트는 파일 최상단에 'use client' 명시

## 하지 말아야 할 것

- console.log를 프로덕션 코드에 남기지 말 것 (logger 사용)
- any 타입 사용 금지 (unknown 쓰고 타입 가드)
- .env 파일 절대 커밋하지 말 것
- DB 스키마 변경은 반드시 마이그레이션으로 (직접 SQL 금지)
- 새 라이브러리 추가 전에 먼저 물어볼 것

## 테스트 규칙

- 새 기능에는 반드시 테스트 작성
- 테스트 파일은 대상 파일과 같은 위치에 *.test.ts
- 외부 API는 모킹 처리

---

효과 없는 CLAUDE.md의 특징 (이러지 마라)

여러 글에서 공통적으로 지적하는 실패 패턴이 있다. 나도 처음에 이 함정에 빠졌었다.

1. 성격(personality) 지시만 잔뜩

❌ 이런 거 효과 없다

- 시니어 엔지니어처럼 행동해줘
- 답변하기 전에 깊이 생각해줘
- 철저하고 신중하게 작업해줘
- 최고의 코드를 작성해줘

이런 추상적인 지시는 Claude의 행동을 측정 가능한 수준으로 바꾸지 못한다. 그럴듯해 보이지만 실제 효과는 거의 제로다. 신호 대 잡음 비율(signal-to-noise)이 바닥이라, 정작 중요한 규칙이 이런 노이즈에 묻혀버린다.

2. 너무 긴 파일

"관련된 거 다 넣자"는 마음으로 시작하면 어느새 수백 줄짜리 괴물 파일이 된다. 스캔이 불가능하고, 중복이 생기고, 진짜 중요한 규칙이 묻힌다.

권장: 200줄 이내로 유지하자. 컨텍스트 윈도우는 유한한 자원이고, CLAUDE.md가 길수록 실제 코드를 위한 공간이 줄어든다.

3. 구체적이지 않은 규칙

❌ "코드를 깔끔하게 작성해줘"
✅ "함수는 한 가지 일만 하도록 작성하고, 20줄을 넘으면 분리해줘"

❌ "테스트를 잘 작성해줘"
✅ "각 함수마다 정상 케이스 1개, 엣지 케이스 최소 2개의 테스트를 작성해줘"

측정 가능하고 구체적인 규칙을 써야 한다. 추상적인 형용사("깔끔하게", "잘", "효율적으로")는 Claude가 해석할 여지가 너무 크다.

---

@ import로 모듈화하기

CLAUDE.md가 길어지면 @경로/파일.md 문법으로 다른 파일을 가져올 수 있다.

# 프로젝트 개요
...

## 상세 규칙
코딩 컨벤션은 @docs/coding-standards.md 참고
API 설계 규칙은 @docs/api-conventions.md 참고

이렇게 하면 메인 CLAUDE.md는 간결하게 유지하면서, 필요한 상세 내용을 분리할 수 있다.

💡 주의: import도 결국 컨텍스트를 차지한다. 정말 유용한 것(코딩 표준, API 컨벤션, 아키텍처 결정)만 import하자. 모든 걸 다 넣으면 모듈화의 의미가 없다.

개인 설정을 팀 프로젝트에 섞고 싶다면, 홈 디렉토리 파일을 import하는 방법도 있다:

@~/personal-preferences.md

이러면 개인 취향은 커밋 안 하면서 적용할 수 있다.

---

.claude/rules/ 로 규칙 관리하기

최근 버전에서는 .claude/rules/ 디렉토리에 규칙 파일을 두면 자동으로 로드된다. import 안 해도 Claude Code가 알아서 읽는다.

.claude/
└── rules/
    ├── typescript.md
    ├── testing.md
    └── git-workflow.md

이 파일들은 메인 CLAUDE.md와 함께 로드되고, Git에 커밋되니까 팀 전체가 공유한다. 규칙이 많아지면 이렇게 주제별로 나누는 게 메인 파일을 비대하게 만드는 것보다 낫다.

---

Auto Memory — Claude가 스스로 쓰는 메모

CLAUDE.md가 내가 쓰는 파일이라면, Auto Memory는 Claude가 스스로 쓰고 관리하는 메모다. 일종의 AI의 노트북이다.

작업하면서 Claude가 프로젝트에 대해 학습한 것들을 자동으로 기록해둔다:

• 프로젝트 패턴: 발견한 빌드 명령어, 테스트 컨벤션, 코드 스타일
• 디버깅 인사이트: 같이 해결한 까다로운 문제의 해법
• 아키텍처 노트: 핵심 파일, 모듈 구조

이건 ~/.claude/projects/<프로젝트>/memory/에 저장된다. 내가 일일이 안 알려줘도 Claude가 알아서 축적하니까, CLAUDE.md에는 핵심 규칙만 쓰고 세세한 건 Auto Memory가 학습하게 두면 된다.

역할 분담: 명시적이고 중요한 규칙 → CLAUDE.md, 세부적인 패턴 학습 → Auto Memory

---

세션 중에 CLAUDE.md를 수정했다면

CLAUDE.md는 세션 시작할 때만 자동으로 로드된다. 작업 도중에 파일을 수정했으면 Claude는 그걸 모른다.

이때는 프롬프트에서 @CLAUDE.md를 언급하면 Claude가 파일을 다시 읽는다.

@CLAUDE.md 방금 업데이트한 규칙 반영해서 작업해줘

또는 세션을 새로 시작하면 당연히 최신 버전이 로드된다.

---

실전 팁

1. 처음부터 완벽하게 쓰려고 하지 마라

빈 파일 앞에서 막막하면 /init으로 초안을 만들고 시작하자. 그리고 작업하면서 "이거 반복 설명하네" 싶은 게 나올 때마다 # 키로 추가하면 된다. 점진적으로 다듬어가는 게 현실적이다.

2. 팀 프로젝트면 반드시 Git에 커밋

CLAUDE.md를 커밋하면 팀원 전체가 같은 컨텍스트에서 Claude를 쓸 수 있다. 코드 스타일이 통일되고, 온보딩도 빨라진다. 신입이 들어와도 Claude가 프로젝트 규칙을 이미 알고 있는 셈이다.

3. 주기적으로 정리하자

프로젝트가 진행되면서 CLAUDE.md도 낡는다. 기술 스택이 바뀌거나, 규칙이 추가되거나. 한 달에 한 번 정도는 들여다보면서 쓸모없어진 규칙을 지우고, 새 규칙을 추가하자. 200줄 넘어가면 모듈화를 고민하고.

4. "왜"를 적으면 더 잘 따른다

❌ "직접 SQL 쓰지 말 것"
✅ "직접 SQL 쓰지 말 것 (마이그레이션 이력 추적이 안 되고, 
    여러 환경 간 스키마 불일치가 생기기 때문)"

이유를 적어두면 Claude가 규칙의 의도를 이해하고, 비슷한 상황에서도 일관되게 판단한다.

---

마무리

CLAUDE.md는 단순한 설정 파일이 아니라, Claude Code를 제대로 쓰기 위한 핵심이다. 한 시간 투자해서 잘 써두면, 그 뒤로 수십 시간의 반복 설명을 아낄 수 있다.

핵심 정리:

• CLAUDE.md는 Claude가 세션마다 자동으로 읽는 프로젝트 설명서다
• 글로벌/프로젝트/개인 3계층이 있고, 구체적인 것이 우선한다
• 성격 지시("시니어처럼 행동해줘")는 효과 없다. 구체적이고 측정 가능한 규칙을 쓰자
• 200줄 이내로 유지하고, 길어지면 @import나 .claude/rules/로 모듈화하자
• /init으로 시작하고 # 키로 점진적으로 추가하자
• 세부 패턴은 Auto Memory가 학습하니까, CLAUDE.md에는 핵심만 쓰자
• 팀 프로젝트면 Git에 커밋해서 공유하자