CLAUDE.md 파일 작성법 — 프로젝트 컨텍스트 설정으로 AI 코딩 속도 10배 올리기

CLAUDE.md가 뭔데 이렇게 중요할까요?

Claude Code를 쓰면서 매번 이런 경험 해보신 적 없으신가요? "이 프로젝트는 Zustand 쓰는데 왜 Redux를 추천하지?", "파일 구조를 맨날 다시 설명해야 하네", "건드리지 말라고 한 auth 모듈을 또 수정했네". 이런 문제는 전부 CLAUDE.md 파일 하나로 해결됩니다.

CLAUDE.md는 프로젝트 루트에 놓는 마크다운 파일입니다. Claude Code가 세션을 시작할 때 이 파일을 가장 먼저 읽습니다. 쉽게 말하면 "이 프로젝트에서 지켜야 할 규칙서"를 AI에게 항상 들고 있게 하는 것입니다.

필자는 바이브코딩으로 실제 앱을 여러 개 출시하고 운영하고 있는데요, CLAUDE.md를 제대로 세팅한 전후로 생산성 차이가 체감상 10배는 납니다. 과장이 아닙니다. 오늘은 필자가 실제로 쓰는 CLAUDE.md 구조를 5개 섹션으로 나눠서 하나하나 설명해드리겠습니다.

섹션 1: 프로젝트 정체성 — "우리가 뭘 만들고 있는지"

첫 번째 섹션은 프로젝트의 기본 정보입니다. 여기서 핵심은 구체적으로 쓰는 것입니다.

# Project: GodLife Pixel
한국 시장 타겟 비주얼 습관 트래커 앱
- Stack: Expo 55, TypeScript strict, Zustand, Supabase
- Target: iOS + Android (EAS Build)
- Language: 한국어 UI, 영어 코드/주석

왜 이게 중요할까요? 이걸 안 쓰면 Claude가 React(웹)로 코드를 짜거나, JavaScript로 작성하거나, 웹 전용 프로젝트 구조를 만들어버립니다. 2분만 투자하면 이후 수십 시간의 수정 작업을 아낄 수 있습니다.

섹션 2: 아키텍처 규칙 — "파일은 어디에 두는지"

프로젝트의 폴더 구조와 패턴을 명시하는 섹션입니다. Claude가 새 파일을 만들 때 이 규칙을 따르게 됩니다.

# Architecture
- Components: src/components/ (아토믹 디자인)
- Screens: src/screens/{기능명}/
- State: src/store/ (Zustand 슬라이스, Redux 사용 금지)
- API: src/api/ (타입이 있는 서비스 함수)
- Types: src/types/ (공유 TypeScript 인터페이스)
- Navigation: Expo Router 파일 기반 라우팅

이걸 쓰고 나면 Claude가 생성하는 모든 새 파일이 정확한 위치에 만들어집니다. 컴포넌트를 lib/에 만든다거나, 스크린을 pages/에 만드는 일이 사라집니다.

섹션 3: 코딩 컨벤션 — "코드 스타일 통일"

이 섹션이 없으면 Claude의 응답마다 코딩 스타일이 달라집니다. 어떤 때는 클래스 컴포넌트, 어떤 때는 함수형. 어떤 때는 default export, 어떤 때는 named export. 이걸 명시적으로 잡아줍니다.

# Conventions
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- Named exports 사용 (default export 금지)
- 모든 스크린에 Error Boundary 적용
- API 호출은 반드시 try/catch로 감싸고 사용자 에러 메시지 표시
- const > let, var 사용 금지
- async/await 사용 (.then() 체인 금지)
- 비즈니스 로직 주석은 한국어, 기술 주석은 영어

실천 팁: 프로젝트에 이미 있는 코드를 훑어보고, 본인이 쓰는 패턴을 그대로 적으시면 됩니다. Claude가 만드는 코드가 기존 코드와 일관되게 됩니다.

섹션 4: 경계선 — "절대 하지 말아야 할 것" (가장 중요)

대부분의 개발자가 이 섹션을 빠뜨리는데요, 이게 사실 가장 중요한 섹션입니다. 필자가 이걸 추가하게 된 계기는 뼈아픈 경험 때문입니다.

한번은 Claude에게 "프로필 화면 개선해줘"라고 요청했는데, Claude가 "도움이 될 것 같아서" 인증 모듈까지 리팩토링해버렸습니다. 앱 전체가 깨졌습니다. 그날 이후 바로 NEVER 리스트를 만들었습니다.

# Boundaries
NEVER:
- auth 모듈(src/api/auth.ts)을 명시적 승인 없이 수정
- 테스트 파일 삭제 또는 이름 변경
- 마이그레이션 계획 없이 DB 스키마 변경
- 먼저 물어보지 않고 새 의존성 설치
- 요청하지 않은 기존 코드 리팩토링

ALWAYS:
- 현재 작업 범위 밖의 파일 수정 전 반드시 확인
- 기존 에러 핸들링 패턴 유지
- PR 제안 전 타입 체크 실행

핵심은 NEVER 리스트입니다. AI가 "도움이 될 것 같아서" 멋대로 하는 것을 원천 차단해줍니다. 이 섹션 하나만으로도 CLAUDE.md를 만들 가치가 있습니다.

섹션 5: 프로젝트 고유 지식 — "이 프로젝트만의 함정들"

모든 프로젝트에는 "문서에 안 나오는데 아는 사람만 아는 것"이 있습니다. 레거시 결정, 알려진 버그, 환경별 차이 같은 것들입니다.

# Knowledge
- AdMob: 개발 환경에서는 테스트 ID 사용, 실제 ID는 프로덕션 빌드에서만
- Supabase RLS: 모든 테이블에 Row Level Security 활성화됨
- EAS Build: dev 프로파일은 internal distribution 사용
- 알려진 이슈: Zustand persist 미들웨어가 Android의 Expo SecureStore와 충돌
- /legacy 엔드포인트는 동작하지만 deprecated됨, 사용 금지

이 섹션이 없으면 Claude는 반드시 이 지뢰밭 중 하나를 밟게 됩니다. 그리고 디버깅에 30분~1시간이 날아갑니다. 5분만 투자하면 이걸 방지할 수 있습니다.

실제 결과: Before vs After

필자가 2주간 CLAUDE.md 유무에 따른 차이를 직접 추적한 결과입니다.

CLAUDE.md 없을 때:

Claude 응답당 평균 3~4번 수정 지시를 해야 했습니다. "아니 Zustand 쓰라고", "그 폴더 아니고 src/components/에 넣어" 같은 것들이죠. 세션 시작할 때마다 15분씩 프로젝트를 설명해야 했고, 요청하지 않은 리팩토링으로 다른 부분이 깨지는 일도 빈번했습니다. 파일마다 코딩 스타일도 제각각이었습니다.

CLAUDE.md 넣은 후:

수정 지시가 응답당 0~1번으로 감소했습니다. 세션 시작 시 컨텍스트 설명 시간이 제로가 되었고, NEVER 리스트 덕분에 무단 리팩토링이 완전 차단되었습니다. 모든 새 파일이 기존 프로젝트 패턴과 일치하게 되었습니다.

고급 팁 4가지

팁 1: 하위 디렉토리 CLAUDE.md 활용하기

Claude Code는 하위 폴더의 CLAUDE.md도 읽습니다. 루트 파일을 상속하면서 로컬 컨텍스트를 추가하는 구조입니다.

project/
├── CLAUDE.md              (전역 규칙)
├── src/
│   ├── components/
│   │   └── CLAUDE.md      (컴포넌트 패턴, prop 규칙)
│   └── api/
│       └── CLAUDE.md      (API 패턴, 에러 처리)

프로젝트가 커지면 하나의 CLAUDE.md로는 한계가 옵니다. 이 계층 구조를 일찍 도입하면 나중에 편합니다.

팁 2: Git에 커밋하세요

CLAUDE.md는 코드베이스의 일부입니다. Git에 커밋해두면 팀원이 합류하거나, 한 달 후에 프로젝트로 돌아왔을 때 가장 빠른 온보딩 문서가 됩니다.

팁 3: 문제가 생길 때마다 업데이트하세요

Claude가 예상 밖의 행동을 할 때마다 "CLAUDE.md에 규칙을 추가했으면 방지할 수 있었나?"를 자문해보세요. 답이 "예"라면 즉시 추가하시면 됩니다. 필자의 CLAUDE.md는 몇 달간 꾸준히 성장해왔고, 갈수록 정교해지고 있습니다.

팁 4: 500줄을 넘기지 마세요

너무 짧으면 컨텍스트가 부족하고, 너무 길면 중요한 규칙이 묻힙니다. 대부분의 프로젝트에서 100~300줄이 최적입니다. 500줄을 넘기면 하위 디렉토리 파일로 분리하는 걸 권장합니다.

지금 바로 복사해서 쓸 수 있는 스타터 템플릿

아래 템플릿을 프로젝트 루트에 CLAUDE.md로 저장하고, 괄호 안을 본인 프로젝트에 맞게 채우시면 됩니다.

# Project: [프로젝트명]
[한 줄 설명]

## Stack
- Framework: [예: Next.js 16 / Expo 55 / Express]
- Language: [예: TypeScript strict]
- State: [예: Zustand / Redux / Context]
- Database: [예: Supabase / Firebase / PostgreSQL]
- Deployment: [예: Vercel / EAS / Docker]

## Architecture
- [폴더]: [역할]
- [폴더]: [역할]

## Conventions
- [코딩 스타일 규칙]
- [네이밍 규칙]
- [import 순서]

## Boundaries
NEVER:
- [Claude가 절대 하면 안 되는 것]

ALWAYS:
- [Claude가 항상 해야 하는 것]

## Knowledge
- [프로젝트 고유 정보]
- [알려진 이슈]
- [환경별 주의사항]

마무리: 컨텍스트가 곧 생산성입니다

CLAUDE.md는 단순한 설정 파일이 아닙니다. "대충 도와주는 AI"와 "내 프로젝트를 이해하는 AI" 사이의 다리입니다. 5개 섹션, 100줄 이내로 시작해보세요. 일주일만 써보시면 없이 코딩하던 시절로 돌아갈 수 없을 겁니다.

다음 글에서는 Cursor 사용자를 위한 .cursorrules 파일 세팅법을 다룰 예정입니다.

이 글에 소개된 서비스와 도구는 작성 시점 기준이며, 업데이트에 따라 변경될 수 있습니다.