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라는 이름으로 파일을 만듭니다.
my-project/
CLAUDE.md ← 여기에 둡니다
src/
package.json
...Claude Code는 프로젝트 폴더에서 실행될 때 자동으로 이 파일을 찾아 읽습니다.
/init 명령을 통한 CLAUDE.md 자동 생성
사실 CLAUDE.md를 처음부터 손으로 쓸 필요는 없습니다. Claude Code에는 /init 이라는 전용 명령이 있습니다.처음 프로젝트를 시작하거나 진행 중이던 프로젝트에 Claude를 처음 도입한다면, 프로젝트 폴더에서 Claude Code를 실행한 뒤 아래의 명령을 입력하면 됩니다.
/init이 명령을 입력하면 Claude Code가 현재 폴더의 파일들 — package.json, 폴더 구조, 설정 파일 등 — 을 스스로 훑어보고 프로젝트에 맞는 CLAUDE.md 초안을 자동으로 만들어주는 것을 확인할 수 있습니다. 기술 스택·폴더 구조·실행 방법 같은 기본 뼈대가 한 번에 채워집니다.
다만 /init이 만든 파일을 그대로 두면 안 됩니다. Claude Code가 코드만 보고 짐작한 내용이라 실제 의도와 다르거나 빠진 규칙이 있을 수 있습니다. /init은 어디까지나 편리한 출발점입니다. 아래에서 설명하는 ‘좋은 CLAUDE.md’의 기준으로 직접 읽어보고 다듬거나, Claude Code와의 대화를 통해 구체적인 내용을 수정하는 과정이 필요합니다.
이미
CLAUDE.md가 있는 상태에서/init을 다시 실행하면 기존 내용을 토대로 새롭게 프로젝트를 파악해 문서를 보완할 수도 있습니다.
CLAUDE.md에 담아야 할 내용
좋은 CLAUDE.md의 판단은 새로운 팀원이 프로젝트를 이해할 수 있도록 상세하게 설명하는 문서인지 생각하면 됩니다. 대체로 아래의 내용들이 포함됩니다.
1. 프로젝트 개요 이 프로젝트가 무엇을 하는 서비스인지 한두 문장으로 설명합니다.
2. 기술 스택 어떤 언어와 프레임워크, 라이브러리를 사용하는지 명시합니다.
3. 폴더 구조 주요 폴더가 어떤 역할을 하는지 설명합니다.
4. 실행 방법 개발 서버를 어떻게 실행하는지, 빌드는 어떻게 하는지 적습니다.
5. 중요 규칙과 주의사항 코딩 스타일, 절대 건드리면 안 되는 파일, 특별히 주의해야 할 사항을 적습니다.
좋은 CLAUDE.md vs 나쁜 CLAUDE.md
실제 예시로 비교해봅니다.
나쁜 CLAUDE.md — 너무 짧고 추상적
# 내 프로젝트
React로 만든 웹사이트입니다.이 정도 정보로는 Claude Code가 어떤 버전의 React를 쓰는지, 상태 관리는 어떻게 하는지, 스타일링은 어떤 방식인지 알 수 없습니다. 이 문서로도 작업을 진행할 수는 있겠지만, 오류를 범할 가능성이 커서 프로젝트의 안정성과 유지도 차원에서 위험 요인이 됩니다.
좋은 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만 씁니다.
- 새 패키지 설치 전에 반드시 확인을 요청하세요.프로젝트의 목표와 지향점, 기술적 사양, 구조, 배포와 주의사항들이 포함되어 있습니다. 프로젝트에 대해 잘 모르는 상태에서 수정을 진행하더라도 오해의 범위가 크게 줄어들며, 치명적인 실수를 줄이거나 없앨 수 있어 바이브코딩 프로젝트의 안정성이 올라갑니다.
프로젝트의 시기와 성격에 따라 다르게
프로젝트를 막 시작해서 아직 구조가 없거나 애초에 모든 항목을 작성할 수 없는 프로젝트라면, 준비된 내용들만 기술해도 됩니다.
# 프로젝트 개요
카페 메뉴 추천 웹서비스를 만들려고 한다.
사용자가 기분과 날씨를 선택하면 어울리는 음료를 추천해준다.
## 기술 방향
- 최대한 단순하게, 라이브러리를 많이 쓰지 않는 방향으로
- 백엔드 없이 프론트엔드만으로 구현
- HTML, CSS, 바닐라 JavaScript로 시작이런 식으로 프로젝트 성격이나 시기 등에 따라 문서의 크기나 범주가 달라질 수 있습니다. 중요한 것은 프로젝트를 잘 이해하고 기억할 수 있도록 돕는 ‘일종의 인수인계 문서로서 내용이 잘 갖춰졌는가’ 판단하는 것입니다.
CLAUDE.md 업데이트
CLAUDE.md는 한 번 쓰고 끝나는 문서가 아닙니다. 프로젝트의 변화에 따라 주기적으로 업데이트해야 합니다.
업데이트가 필요한 상황은 이렇습니다.
- 새 라이브러리나 프레임워크를 도입했을 때
- 폴더 구조가 크게 바뀌었을 때
- 새로운 코딩 규칙을 정했을 때
- Claude Code가 계속 같은 실수를 반복할 때 (그 실수를 주의사항으로 추가)
특히 마지막 상황이 중요합니다. Claude Code가 같은 방식으로 틀린다면 그것은 CLAUDE.md에 명시되지 않은 규칙이 있다는 신호입니다.
정리
CLAUDE.md는 Claude Code와 함께 프로젝트를 만들 때 가장 기본이 되는 파일입니다. 이 파일을 잘 작성해두면 Claude Code가 프로젝트의 맥락을 이해하고 일관성 있는 코드를 만들어냅니다. 짧아도 괜찮으니, 지금 당장 프로젝트에 기술 스택과 주요 규칙만 담은 CLAUDE.md부터 만들어보세요.
다음 편에서는 Claude Code와 함께 실제로 첫 번째 화면을 만드는 과정을 단계별로 따라가봅니다.