5장: CLAUDE.md — AI에게 나를 기억시키기
CLAUDE.md가 왜 중요한가
Claude Code는 새 대화를 시작할 때마다 아무것도 모릅니다. 어제 어떤 작업을 했는지, 이 프로젝트가 어떤 기술 스택을 쓰는지, 코드를 어떻게 작성하길 원하는지 — 전부 처음부터 알려줘야 합니다.
매번 같은 말을 반복하는 건 불편합니다.
이 프로젝트는 Next.js 16를 쓰고 있어.
Supabase를 데이터베이스로 써.
컴포넌트는 /components 폴더에 넣어.
주석은 한국어로 작성해.
외부 라이브러리는 추가하기 전에 먼저 물어봐.
CLAUDE.md는 이걸 한 번만 적어두면 해결됩니다. 프로젝트 폴더에 CLAUDE.md 파일을 만들어두면 Claude Code가 대화를 시작할 때 자동으로 읽습니다. 이후부터는 매번 설명하지 않아도 됩니다.
/init — 자동으로 만들기
프로젝트 폴더에서 Claude Code를 켜고 /init을 입력하면 자동으로 CLAUDE.md를 만들어줍니다.
/init
Claude Code가 프로젝트 구조를 분석해서 빌드 시스템, 테스트 프레임워크, 코드 패턴 등을 파악하고 초안을 작성합니다. 처음부터 직접 쓰는 것보다 이 초안을 수정하는 게 훨씬 빠릅니다.
좋은 CLAUDE.md의 구조
CLAUDE.md에 무엇을 적을지 막막하다면 이 항목들을 참고하세요.
넣어야 할 것들
프로젝트 개요 — 이 프로젝트가 무엇인지 한두 문장으로.
# 프로젝트 개요
온라인 독서 모임 플랫폼. 모임 개설, 책 선정, 참여자 관리 기능을 제공한다.
기술 스택 — 어떤 프레임워크와 라이브러리를 쓰는지. Claude Code가 파악하지 못할 수도 있는 것들을 명시합니다.
## 기술 스택
- Frontend: Next.js 16 (App Router), TypeScript, Tailwind CSS
- Backend: Supabase (PostgreSQL, Auth, Storage)
- 배포: Vercel
자주 쓰는 명령어 — 개발 서버 실행, 빌드, 테스트 명령어 등.
## 명령어
- 개발 서버: npm run dev (포트 3000)
- 빌드: npm run build
- DB 스키마 반영: npm run db:migrate
코딩 규칙 — 이 프로젝트에서만 통용되는 규칙들. Claude Code가 코드를 읽어도 알기 어려운 것들입니다.
## 코딩 규칙
- 주석은 한국어로 작성
- 외부 라이브러리 추가 전 반드시 먼저 물어볼 것
폴더 구조 — 어디에 무엇을 두는지 약속.
## 폴더 구조
- /app — 페이지 라우트
- /components — 재사용 컴포넌트
- /lib — 유틸리티, API 클라이언트
- /types — TypeScript 타입 정의
자주 실수하는 것들 — AI가 반복적으로 틀리는 부분을 발견할 때마다 추가.
## 주의사항
- Supabase 클라이언트는 /lib/supabase.ts에서 import할 것, 직접 초기화 금지
- 환경변수는 NEXT*PUBLIC* 접두사 없이는 클라이언트에서 접근 불가
- useEffect 안에서 직접 fetch 하지 말고 React Query 사용
넣지 말아야 할 것들
파일 내용을 길게 설명하거나, Claude Code가 코드를 읽으면 알 수 있는 것들, "클린 코드를 작성해" 같은 당연한 말들은 빼는 게 낫습니다. CLAUDE.md가 너무 길어지면 Claude Code가 중요한 규칙을 놓칩니다.
공식 문서의 기준은 명확합니다. "이 항목을 지우면 Claude Code가 실수를 할까?" — 그렇지 않으면 지웁니다.
계속 다듬어가기
Claude Code를 만든 Boris Cherny는 이렇게 말합니다.
"AI를 교정할 때마다 마지막에 'CLAUDE.md를 업데이트해서 이 실수를 다시 하지 않게 해'라고 말하세요."
CLAUDE.md는 한 번 쓰고 끝내는 게 아닙니다. 프로젝트를 만들어가면서 계속 다듬습니다.
실제 흐름은 이렇습니다.
Claude Code가 컴포넌트를 엉뚱한 폴더에 만들었습니다.
그건 /components/ui 폴더에 넣어야 해.
이 규칙을 CLAUDE.md에도 추가해줘.
Claude Code가 영어 주석을 썼습니다.
주석은 항상 한국어로 써줘.
CLAUDE.md에 이 규칙 추가해줘.
이렇게 하면 같은 실수가 반복되지 않습니다. 시간이 지날수록 CLAUDE.md가 정제되고, AI가 점점 더 여러분의 방식대로 작업하게 됩니다.
CLAUDE.md 파일 위치
CLAUDE.md는 여러 위치에 둘 수 있습니다.
프로젝트 루트 (./CLAUDE.md) — 가장 일반적입니다. 해당 프로젝트에서만 적용됩니다. Git에 올려서 팀원과 공유할 수 있습니다.
홈 폴더 (~/.claude/CLAUDE.md) — 모든 프로젝트에 공통으로 적용됩니다. "항상 한국어로 답해", "코드 설명은 간결하게" 같은 개인 스타일을 적어두기 좋습니다.
하위 폴더에도 CLAUDE.md를 둘 수 있습니다. Claude Code가 그 폴더의 파일을 작업할 때 자동으로 읽습니다. 규모가 큰 프로젝트에서 특정 모듈만의 규칙을 따로 관리할 때 유용합니다.
✏️ 실습: 내 프로젝트용 CLAUDE.md 만들어보기
1단계: Code 탭에서 Select folder를 눌러 my-project라는 새 폴더를 만들고 선택합니다.
2단계: /init을 입력합니다.
/init
Claude Code가 폴더를 분석해서 CLAUDE.md 초안을 만들어줍니다. 지금은 빈 폴더라서 기본 구조만 나올 겁니다.
3단계: 대화에 나온 CLAUDE.md 경로를 클릭해서 내용을 확인합니다.
4단계: Claude Code에게 내 프로젝트에 맞게 수정을 요청합니다.
CLAUDE.md를 수정해줘.
이 프로젝트는 Next.js + Supabase로 만드는 블로그야.
기술 스택, 폴더 구조, 코딩 규칙을 추가해줘.
주석은 한국어, 외부 라이브러리 추가 전에 먼저 물어볼 것도 넣어줘.
5단계: 결과를 확인하고, 빠진 게 있으면 직접 추가합니다. 파일 패널에서 CLAUDE.md를 열어 고치고 Save를 눌러도 됩니다.
이렇게 만든 CLAUDE.md가 다음 장부터 시작할 실전 프로젝트의 기반이 됩니다.
참고자료