[Claude Code 실전 정복 #3] CLAUDE.md 완전 정복 — 설정 한 번으로 매 세션이 달라지는 이유 (2026)

 

시리즈: Claude Code 실전 정복 | 3편

작성자: 체리플랜 | 7년차 프론트엔드 개발자

• 1편: [Claude Code 설치부터 첫 실행까지]
• https://cherrycoding0.tistory.com/46

[Claude Code 실전 정복 #1] 설치부터 첫 실행까지 — 7년차 개발자가 겪은 진짜 과정 (2026)

• 2편: [VS Code 연동 + 실전 워크플로우]
• https://cherrycoding0.tistory.com/47

[Claude Code 실전 정복 #2] VS Code 연동 + 실전 워크플로우 — 7년차 개발자의 프롬프트 패턴 공개 (2026

 

---

CLAUDE.md 없이 Claude Code 쓰고 있었다면, 지금까지 토큰을 절반 이상 낭비한 거예요.

저도 처음에 몰랐어요. Claude Code 설치하고 한동안 그냥 썼어요. 그런데 매 세션마다 반복하는 게 있었어요.

"이 프로젝트는 React 18이고요, Vite 쓰고 있고요, TypeScript는 안 써요, 컴포넌트는 함수형으로만 써요, CSS는 Tailwind 없이 직접 유틸 클래스 만든 part-addon.css 쓰고 있어요..."

이걸 매번 설명하는 거예요. 세션 시작마다. 심지어 같은 프로젝트 작업하는데도.

CLAUDE.md 알고 나서 이게 싹 사라졌어요.

프로젝트 루트에 파일 하나 만들어두면, Claude Code가 세션 시작할 때마다 자동으로 읽어요. 제 프로젝트를 아는 상태로 시작하는 거예요. 온보딩 문서 한 번 써주면 영원히 기억하는 신입 동료 같은 느낌이에요.

이번 편에서는 제가 실제로 cherryplan 허브 프로젝트에 쓰고 있는 CLAUDE.md를 공개하면서, 어떻게 작성하면 좋은지 정리할게요.

---

CLAUDE.md가 뭔가요?

Claude Code가 세션 시작마다 자동으로 읽는 프로젝트 설명 파일이에요.

프로젝트 루트에 CLAUDE.md 파일을 만들어두면 끝이에요. 특별한 설정 없어도 Claude Code가 알아서 찾아서 읽어요.

공식 문서에서는 이렇게 설명해요. "CLAUDE.md는 코드만으로는 파악할 수 없는 맥락 — 빌드 명령어, 코드 스타일, 워크플로우 규칙 — 을 Claude에게 주는 파일이다."

즉, 코드 읽으면 알 수 있는 것들은 굳이 안 써도 돼요. 코드만 봐서는 모르는 것들 — 내가 원하는 작업 방식, 건드리면 안 되는 것들, 프로젝트 특수 사항 — 을 담는 게 핵심이에요.

---

CLAUDE.md가 없을 때 vs 있을 때

제가 직접 경험한 차이예요.

CLAUDE.md 없을 때

세션 시작할 때마다 프로젝트 배경 설명을 해야 했어요.

이 프로젝트는 React 18 + Vite로 만든 포트폴리오 허브예요.
Tailwind 없이 직접 만든 CSS 유틸 클래스(part-addon.css)를 써요.
TypeScript는 안 쓰고 JavaScript예요.
컴포넌트는 함수형으로만 써요.
...

이게 토큰이에요. 설명하는 데만 수백 토큰 써요. 그리고 이게 매 세션마다 반복돼요.

더 문제인 건, 이걸 안 하면 Claude Code가 프로젝트 맥락 모르는 상태로 답변해요. "TypeScript로 바꾸면 어때요?", "Tailwind 설치해요", "useState 대신 Redux 써봐요" 같은 내 프로젝트랑 안 맞는 제안이 나와요.

CLAUDE.md 있을 때

세션 시작하면 Claude Code가 파일을 먼저 읽어요. 그다음부터는 설명 없이 바로 작업 들어갈 수 있어요.

BudgetSummary 컴포넌트에 카테고리 필터 추가해줘.

이 한 줄만 해도 Claude Code가 어떤 프레임워크인지, 어떤 스타일로 짜야 하는지, 어떤 파일 건드려야 하는지 이미 알고 있어요. 바로 일 시작하는 거예요.

토큰 절약 + 결과물 품질 향상 + 속도 향상 — 이 세 가지가 동시에 돼요.

---

CLAUDE.md 위치 — 어디에 두나요?

CLAUDE.md는 위치에 따라 적용 범위가 달라요.

위치 적용 범위

~/.claude/CLAUDE.md	모든 프로젝트에 전역 적용
./CLAUDE.md (프로젝트 루트)	해당 프로젝트에만 적용, 팀 공유 가능
./CLAUDE.local.md	해당 프로젝트, 개인용 (gitignore 권장)
하위 디렉토리 CLAUDE.md	해당 디렉토리 작업 시 추가 로드

저는 두 가지를 같이 써요.

• ~/.claude/CLAUDE.md: 모든 프로젝트에 공통으로 적용할 것들 (작업 방식, 출력 언어 등)
• ./CLAUDE.md (프로젝트 루트): 프로젝트별 스택, 규칙, 주의사항

프로젝트 루트의 CLAUDE.md는 git add 해서 버전 관리에 포함시켜요. 나중에 다른 기기에서 작업하거나 팀원이 생기면 그대로 쓸 수 있어서요.

---

실제 CLAUDE.md 공개 — cherryplan 허브 프로젝트

제가 cherryplan 허브 프로젝트에 쓰고 있는 CLAUDE.md 전체예요.

https://cherryplan.netlify.app/

🍒 CherryPlan

# CherryPlan Hub — CLAUDE.md

## 프로젝트 개요
- React 18 + Vite 기반 포트폴리오 허브
- 9개 미니 앱을 하나의 대시보드로 묶은 SPA
- 배포: Netlify (cherryplan.netlify.app)
- GitHub: cherrycoding0/cherryplan

## 기술 스택
- **프레임워크**: React 18
- **번들러**: Vite
- **언어**: JavaScript (TypeScript 미사용)
- **스타일**: part-addon.css (자체 제작 유틸 클래스, Tailwind 미설치)
- **상태관리**: useState, useContext (Redux/Zustand 미사용)
- **라우팅**: React Router v6

## 포함된 앱 목록
1. 독서기록 (BookLog)
2. 포모도로 타이머 (Pomodoro)
3. 오늘의 메뉴 (MenuPicker)
4. 태스크보드 (TaskBoard)
5. 습관트래커 (HabitTracker)
6. 가계부 (Budget)
7. AI Diary (Claude API 연동)
8. Movie/Drama Log (TMDB API 연동)
9. Mood Tracker

## 디렉토리 구조
src/
├── apps/          # 각 미니앱 폴더
│   ├── Budget/
│   ├── BookLog/
│   └── ...
├── components/    # 공통 컴포넌트
├── hooks/         # 커스텀 훅
├── utils/         # 유틸 함수
└── styles/        # part-addon.css 포함

## 코딩 규칙 (반드시 지켜줘)
- 컴포넌트는 **함수형 컴포넌트**만 사용, 클래스 컴포넌트 금지
- **TypeScript 사용 금지** — .js, .jsx 파일만
- 스타일은 **part-addon.css의 유틸 클래스 사용** — inline style이나 새 CSS 파일 추가 금지
- `any` 타입 사용 금지 (향후 TS 마이그레이션 대비)
- Props는 구조분해할당으로 받기
- 파일명: 컴포넌트는 PascalCase, 유틸/훅은 camelCase

## 주요 명령어
- `npm run dev` — 개발 서버 (포트 5173)
- `npm run build` — 프로덕션 빌드
- `npm run preview` — 빌드 결과 미리보기

## 작업 방식 (중요)
1. 코드 수정 전에 **반드시 계획 먼저 제시**하고 확인 받을 것
2. 한 번에 여러 파일 대규모 수정 금지 — 단계별로 진행
3. 기존 part-addon.css 유틸 클래스 먼저 확인 후 활용
4. 수정 완료 후 변경 사항 요약 제공

## 하면 안 되는 것 (IMPORTANT)
- Tailwind CSS 설치 제안 금지
- Redux, Zustand 등 추가 상태관리 라이브러리 제안 금지
- TypeScript 마이그레이션 제안 금지 (내가 요청할 때만)
- 허락 없이 package.json 의존성 추가 금지
- 클래스 컴포넌트로 작성 금지

## 출력 언어
- 모든 답변은 **한국어**로
- 코드 주석도 한국어
- 에러 설명, 계획 설명 전부 한국어

 

---

좋은 CLAUDE.md 작성 원칙

공식 문서와 실제 경험에서 나온 원칙들이에요.

원칙 1: 짧고 명확하게

CLAUDE.md가 너무 길면 역효과 나요.

공식 문서에도 이게 명시돼 있어요. 파일이 길수록 Claude Code가 중요한 규칙을 놓치는 확률이 올라가요. 각 항목마다 "이게 없으면 Claude가 실수를 하나?" 질문해보고, 아니면 과감하게 빼세요.

원칙 2: 버전 명시가 중요한 이유

## 기술 스택
- React 18  ← 버전 명시
- Next.js 15 ← 버전 명시

버전을 안 쓰면 Claude Code가 자기가 학습한 가장 안정적인(오래된) 버전 기준으로 코드 짜요. Next.js 13이랑 15는 완전히 다른 프레임워크 수준인데, 버전 없으면 구버전 코드가 나와요.

원칙 3: "하면 안 되는 것" 섹션이 핵심

저한테 제일 효과 있었던 섹션이에요.

## 하면 안 되는 것
- Tailwind CSS 설치 제안 금지
- TypeScript 마이그레이션 제안 금지

Claude Code는 기본적으로 "더 좋은 방법" 제안하려는 경향이 있어요. 근데 내 프로젝트 맥락에서는 그게 오히려 방해가 될 때가 있어요. 이미 결정한 것들 — 라이브러리 선택, 아키텍처 결정 — 은 미리 명시해두면 불필요한 제안이 안 나와요.

원칙 4: IMPORTANT 키워드 활용

꼭 지켜야 하는 규칙엔 앞에 IMPORTANT 붙이세요.

## 작업 방식 (IMPORTANT)
- 코드 수정 전 반드시 계획 먼저 제시

공식 문서에서 확인된 내용이에요. IMPORTANT, YOU MUST 같은 강조 표현이 들어가면 Claude Code가 해당 규칙을 더 잘 따라요.

원칙 5: /init 으로 시작하기

처음 CLAUDE.md 쓰는 게 막막하면 이 명령어 쓰세요.

/init

Claude Code가 현재 프로젝트 구조를 분석해서 기본 CLAUDE.md 초안을 만들어줘요. 그걸 베이스로 수정하는 게 훨씬 쉬어요.

---

계층적 CLAUDE.md — 모노레포나 대형 프로젝트에서

프로젝트가 커지면 디렉토리별로 CLAUDE.md를 분리할 수 있어요.

my-project/
├── CLAUDE.md           ← 전체 프로젝트 공통 규칙
├── frontend/
│   └── CLAUDE.md       ← 프론트엔드 특화 규칙
└── backend/
    └── CLAUDE.md       ← 백엔드 특화 규칙

Claude Code가 frontend/ 안에서 작업할 때 루트 CLAUDE.md랑 frontend/CLAUDE.md 둘 다 읽어요. 공통 규칙 + 영역별 특화 규칙이 합쳐지는 구조예요.

@import 문법으로 파일 가져오는 것도 돼요:

# CLAUDE.md
프로젝트 공통 규칙 여기.

## Git 워크플로우
@docs/git-workflow.md 참고.

@docs/git-workflow.md가 자동으로 로드돼요.

---

CLAUDE.md 관리 팁 — 살아있는 문서로 유지하기

CLAUDE.md는 한 번 쓰고 끝이 아니에요. 코드처럼 관리해야 해요.

언제 업데이트하나요?

• 새 라이브러리 추가할 때
• 코딩 컨벤션 바꿀 때
• Claude Code가 계속 같은 실수를 반복할 때 (그게 빠진 규칙이라는 신호)
• 프로젝트 구조가 크게 바뀔 때

Claude Code가 계속 같은 실수를 한다면:

이게 CLAUDE.md 업데이트 타이밍이에요. 예를 들어 Claude Code가 계속 inline style을 쓴다면:

## 스타일 규칙 (IMPORTANT)
- inline style 절대 금지
- part-addon.css 유틸 클래스만 사용
- 새 CSS 파일 추가 금지

이렇게 추가하면 다음 세션부터 안 해요.

git에 커밋하세요:

git add CLAUDE.md
git commit -m "CLAUDE.md: 스타일 규칙 추가"

CLAUDE.md도 코드예요. 버전 관리 하세요.

---

솔직한 한계

CLAUDE.md 규칙을 100% 지켜주는 건 아니에요.

공식 문서에도 나와있는데, CLAUDE.md 지시를 따르는 확률이 약 70% 수준이에요. 스타일 선호도 같은 건 70%도 충분해요. 근데 "절대 이 파일 건드리지 마" 같은 크리티컬한 규칙은 70%로 부족해요.

이런 크리티컬한 규칙은 CLAUDE.md가 아니라 Hooks 기능으로 강제해야 해요. Hooks는 Claude Code의 특정 행동을 스크립트로 강제하는 기능인데, 이건 별도 편에서 다룰게요.

그래도 70%만 돼도 체감 차이가 커요. 매번 설명하다가 한 번만 써두면 70% 이상 지켜주는 걸로 바뀌는 거잖아요.

---

마무리: CLAUDE.md는 Claude Code를 제대로 쓰기 위한 필수 세팅이에요

Claude Code 쓰면서 제일 먼저 해야 할 일이 CLAUDE.md 세팅이에요.

설치하고, 인증하고, CLAUDE.md 만들고 — 이 세 단계까지 해야 Claude Code를 제대로 쓰기 시작한 거예요.

CLAUDE.md 없이 쓰는 건 신입사원한테 온보딩 안 하고 바로 일 시켜놓고 "왜 이렇게 하냐"고 하는 거랑 같아요. 문서 한 번 만들어두면 Claude Code가 내 프로젝트 맥락을 영구적으로 기억해요.

오늘 당장 /init 치고 시작해보세요.

다음 포스팅 예고: [Claude Code 실전 정복 #4] Claude Code로 React 컴포넌트 제대로 만들기 — 함수형 컴포넌트부터 커스텀 훅까지

 

---