CLAUDE.md 작성법 — AI가 내 프로젝트를 이해하게 만드는 방법
Claude Code가 프로젝트 구조와 규칙을 기억하게 만드는 CLAUDE.md 파일의 작성법을 좋은 예시와 나쁜 예시로 설명합니다.
Claude Code를 설치했다면 이제 본격적으로 프로젝트를 만들어볼 차례입니다. 그런데 한 가지 문제가 있습니다. Claude Code는 매우 강력하지만, 내 프로젝트에 대해 아무것도 모릅니다. 어떤 기술을 쓰는지, 폴더가 어떻게 구성되어 있는지, 어떤 규칙을 따르는지 전혀 알지 못합니다.
CLAUDE.md는 이 문제를 해결합니다. 프로젝트 폴더 안에 놓으면 Claude Code가 작업을 시작할 때마다 자동으로 이 파일을 읽어 프로젝트의 맥락을 이해합니다. 잘 작성된 CLAUDE.md 하나가 AI의 작업 품질을 크게 바꿔놓습니다.
CLAUDE.md가 필요한 이유
바이브코딩을 처음 시작하면 이런 경험을 하게 됩니다.
처음에는 Claude Code가 원하는 대로 코드를 잘 만들어줍니다. 그런데 시간이 지나 프로젝트가 커지면 AI가 엉뚱한 방식으로 코드를 추가하기 시작합니다. 기존에 쓰던 라이브러리 대신 다른 것을 쓰거나, 폴더 구조 규칙을 무시하거나, 이미 있는 함수를 다시 만들거나 합니다.
이유는 간단합니다. AI는 대화창에 있는 내용만 알고 있기 때문입니다. 새 대화를 시작하거나 시간이 지나면 이전에 정했던 규칙과 구조를 기억하지 못합니다.
CLAUDE.md는 이 문제를 해결하는 가장 기본적이고 효과적인 방법입니다. Claude Code는 매 작업 시작 시 이 파일을 읽어 프로젝트의 현재 상태와 규칙을 파악합니다.
CLAUDE.md를 어디에 두는가
프로젝트의 최상위 폴더(루트 디렉토리)에 CLAUDE.md라는 이름으로 파일을 만듭니다.
my-project/
CLAUDE.md ← 여기에 둡니다
src/
package.json
...Claude Code는 프로젝트 폴더에서 실행될 때 자동으로 이 파일을 찾아 읽습니다.
CLAUDE.md에 담아야 할 내용
좋은 CLAUDE.md는 새로운 팀원에게 프로젝트를 설명하는 문서라고 생각하면 됩니다. AI가 처음 이 프로젝트를 봤을 때 알아야 할 것들을 담습니다.
1. 프로젝트 개요 이 프로젝트가 무엇을 하는 서비스인지 한두 문장으로 설명합니다.
2. 기술 스택 어떤 언어와 프레임워크, 라이브러리를 사용하는지 명시합니다. AI가 엉뚱한 기술을 쓰는 것을 방지합니다.
3. 폴더 구조 주요 폴더가 어떤 역할을 하는지 설명합니다.
4. 실행 방법 개발 서버를 어떻게 실행하는지, 빌드는 어떻게 하는지 적습니다.
5. 중요 규칙과 주의사항 코딩 스타일, 절대 건드리면 안 되는 파일, 특별히 주의해야 할 사항을 적습니다.
좋은 CLAUDE.md vs 나쁜 CLAUDE.md
실제 예시로 비교해봅니다.
나쁜 CLAUDE.md — 너무 짧고 추상적
# 내 프로젝트
React로 만든 웹사이트입니다.이 정도 정보로는 AI가 어떤 버전의 React를 쓰는지, 상태 관리는 어떻게 하는지, 스타일링은 어떤 방식인지 알 수 없습니다. 작업할수록 AI가 제멋대로 기술을 선택하게 됩니다.
좋은 CLAUDE.md — 구체적이고 실용적
# 프로젝트 개요
온라인 독서 모임 플랫폼입니다. 사용자가 모임을 만들고, 책을 등록하고, 일정을 관리할 수 있습니다.
## 기술 스택
- 프론트엔드: React 18, Vite, TailwindCSS
- 백엔드: Node.js 20, Express 4
- 데이터베이스: PostgreSQL 16
- 상태 관리: Zustand (Redux 사용하지 않음)
## 폴더 구조
```
src/
components/ 공통 UI 컴포넌트
pages/ 페이지 단위 컴포넌트
hooks/ 커스텀 훅
api/ API 호출 함수
server/
routes/ API 라우터
data/ DB 쿼리 함수
```
## 실행 방법
```bash
# 프론트엔드
cd src && npm run dev
# 백엔드
cd server && npm run dev
```
## 중요 규칙
- 스타일링은 반드시 TailwindCSS 클래스만 사용합니다. 인라인 스타일, CSS 파일 추가 금지.
- API 호출은 `src/api/` 폴더 안에 함수로 만들고, 컴포넌트에서 직접 fetch 호출 금지.
- TypeScript는 사용하지 않습니다. JavaScript만 씁니다.
- 새 패키지 설치 전에 반드시 확인을 요청하세요.두 번째 예시는 AI가 작업을 시작하자마자 어떤 기술을 써야 하는지, 어디에 파일을 만들어야 하는지 명확하게 알 수 있습니다.
처음 시작하는 프로젝트라면
프로젝트를 막 시작해서 아직 구조가 없다면, 간단하게 의도만 적어도 됩니다.
# 프로젝트 개요
카페 메뉴 추천 웹서비스를 만들려고 합니다.
사용자가 기분과 날씨를 선택하면 어울리는 음료를 추천해줍니다.
## 기술 방향
- 최대한 단순하게, 라이브러리를 많이 쓰지 않는 방향으로 만들고 싶습니다.
- 백엔드 없이 프론트엔드만으로 구현하고 싶습니다.
- HTML, CSS, 바닐라 JavaScript로 시작합니다.이 정도만 있어도 AI가 불필요하게 복잡한 구조를 만드는 것을 막을 수 있습니다.
CLAUDE.md를 업데이트하는 시점
CLAUDE.md는 한 번 쓰고 끝나는 문서가 아닙니다. 프로젝트가 바뀔 때마다 함께 업데이트해야 합니다.
업데이트가 필요한 상황은 이렇습니다.
- 새 라이브러리나 프레임워크를 도입했을 때
- 폴더 구조가 크게 바뀌었을 때
- 새로운 코딩 규칙을 정했을 때
- AI가 계속 같은 실수를 반복할 때 (그 실수를 주의사항으로 추가)
특히 마지막 상황이 중요합니다. AI가 같은 방식으로 틀린다면 그것은 CLAUDE.md에 명시되지 않은 규칙이 있다는 신호입니다.
팁: AI에게 CLAUDE.md 초안을 만들게 하기
프로젝트가 이미 어느 정도 진행됐다면, Claude Code에게 직접 CLAUDE.md 초안을 만들어달라고 요청할 수 있습니다.
현재 프로젝트 구조를 파악해서 CLAUDE.md 파일 초안을 작성해줘.
기술 스택, 폴더 구조, 실행 방법을 포함해줘.AI가 현재 폴더의 파일들을 읽고 초안을 만들어줍니다. 이후 내용을 검토하고 빠진 부분을 직접 채워 넣으면 됩니다.
정리
CLAUDE.md는 AI와 함께 프로젝트를 만들 때 가장 기본이 되는 파일입니다. 이 파일을 잘 작성해두면 AI가 프로젝트의 맥락을 이해하고 일관성 있는 코드를 만들어냅니다. 짧아도 괜찮으니, 지금 당장 프로젝트에 기술 스택과 주요 규칙만 담은 CLAUDE.md부터 만들어보세요.
다음 편에서는 Claude Code와 함께 실제로 첫 번째 화면을 만드는 과정을 단계별로 따라가봅니다.