CLAUDE.md란? 클로드코드가 프로젝트 규칙을 기억하는 방법

클로드코드(Claude Code)에게 기능을 만들어달라고 했는데 컴포넌트를 엉뚱한 폴더에 넣습니다. 프로젝트에서 쓰지 않기로 한 라이브러리를 설치하고, 작업을 마친 뒤 실행해야 하는 테스트도 빠뜨려요.

그때마다 같은 설명을 반복합니다.

이 프로젝트는 Next.js 16을 사용해요.
공용 컴포넌트는 components 폴더에 넣어주세요.
외부 라이브러리를 추가하기 전에 먼저 물어보세요.
수정한 뒤 npm run build를 실행해주세요.

CLAUDE.md는 이런 프로젝트 설명과 작업 규칙을 한 번만 적어두는 파일입니다. 프로젝트 폴더에 만들어두면 클로드코드가 새 대화를 시작할 때 읽기 때문에 매번 같은 내용을 입력하지 않아도 돼요.

하지만 CLAUDE.md가 AI의 영구 기억을 만드는 것은 아닙니다. 실제로 어떤 방식으로 작동하는지 알면 무엇을 적어야 할지도 분명해집니다.

왜 CLAUDE.md를 만드나요?

새로운 개발자가 팀에 들어왔다고 생각해볼게요. 코드를 읽으면 버튼과 함수가 어디에 있는지는 찾을 수 있습니다. 그러나 다음 내용은 코드만 보고 바로 알기 어렵습니다.

• 개발 서버와 테스트를 실행하는 명령어
• 새 파일을 만들어야 하는 폴더
• 데이터베이스 변경 후 거쳐야 하는 절차
• 기술적으로 가능하지만 이 프로젝트에서는 금지한 방식
• 과거에 자주 발생한 실수

사람에게 업무 설명서가 필요하듯 클로드코드에도 프로젝트의 작업 방식을 알려주는 문서가 필요합니다.

코드
→ 현재 기능이 어떻게 구현되어 있는지 보여줌

CLAUDE.md
→ 이 프로젝트에서 어떻게 작업해야 하는지 알려줌

특히 새 대화를 시작할 때 효과가 큽니다. 대화 기록에만 있던 규칙은 새 세션으로 자동 전달되지 않지만, CLAUDE.md에 적은 내용은 다시 불러옵니다. 프로젝트 루트의 파일을 Git에 올리면 팀원도 같은 지침을 사용할 수 있어요.

어떤 메커니즘으로 작동하나요?

클로드코드를 실행하면 현재 폴더와 상위 폴더에서 CLAUDE.md를 찾습니다. 발견한 내용을 현재 세션의 컨텍스트에 넣고, 사용자의 요청과 읽은 코드, 명령어 실행 결과와 함께 참고합니다.

클로드코드 실행
→ CLAUDE.md 탐색
→ 내용을 현재 세션의 컨텍스트에 추가
→ 사용자 요청과 프로젝트 코드를 함께 판단
→ 답변하고 파일 수정

즉, CLAUDE.md가 클로드 모델을 다시 학습시키거나 내부 system prompt를 바꾸는 것은 아닙니다. 매 세션에 프로젝트 지침을 다시 제공하는 방식이에요. 자세한 내용은 클로드코드 메모리 공식 문서 (새 탭에서 열림)에서 확인할 수 있습니다.

여기서 말하는 컨텍스트가 낯설다면 컨텍스트 윈도우란? AI의 작업대 이해하기를 함께 읽어보세요.

대화가 길어졌을 때 컨텍스트를 정리하는 방법은 클로드코드 /clear와 /compact 차이에서 이어서 설명합니다. 새 작업으로 전환할 때는 /clear, 같은 긴 작업을 계속할 때는 /compact를 사용하면 됩니다.

이 차이 때문에 알아둘 점이 두 가지 있습니다.

첫째, 지침이지 강제 장치는 아닙니다. “배포 전에 테스트를 실행한다”고 적으면 클로드가 참고하지만 반드시 실행된다고 보장되지는 않아요. 특정 명령어를 무조건 실행하거나 비밀 파일 접근을 차단해야 한다면 Hook, permissions나 CI 같은 별도의 장치가 필요합니다. CLAUDE.md와 스킬·서브에이전트·훅의 역할 차이는 클로드코드 확장 기능을 고르는 기준에서 이어서 설명합니다.

둘째, 파일이 길수록 좋은 것은 아닙니다. CLAUDE.md도 컨텍스트 공간을 사용합니다. 관련 없는 설명이 많으면 중요한 규칙이 묻힐 수 있어요. Anthropic은 하나의 파일을 200줄 이내로 유지하도록 권장합니다.

어디에 만들면 되나요?

처음에는 프로젝트 루트에 하나만 만들면 충분합니다.

여러 파일이 있으면 하나가 나머지를 덮어쓰는 것이 아니라 함께 컨텍스트에 들어갑니다. 서로 충돌하는 내용을 적지 않는 것이 중요해요. /memory를 실행하면 현재 세션이 어떤 지침 파일을 읽었는지 확인할 수 있습니다.

큰 프로젝트에서는 하위 폴더에 별도의 CLAUDE.md를 둘 수 있습니다. 이 파일은 클로드가 해당 폴더의 코드를 읽을 때 불러옵니다. 관리자 화면에만 필요한 규칙을 고객용 사이트 작업에 항상 포함하지 않아도 되는 거예요.

무엇을 적어야 하나요?

좋은 CLAUDE.md에는 클로드가 모든 작업 전에 알아야 하지만 코드만 봐서는 놓치기 쉬운 내용이 들어갑니다.

1. 프로젝트 구조

## 프로젝트 구조

- `apps/web`: 고객용 사이트
- `apps/admin`: 운영자 대시보드
- `packages/db`: 공용 데이터베이스 스키마

고객용 사이트와 관리자 페이지처럼 여러 앱을 한 저장소에서 관리하는 구조가 낯설다면 모노리포로 만들면 좋은 이유를 먼저 살펴보세요.

2. 검증된 명령어

## 명령어

- 개발 서버: `npm run dev`
- 테스트: `npm test`
- 빌드: `npm run build`
- DB 변경 후: `npm run db:generate`, `npm run db:migrate`

3. 프로젝트만의 규칙과 주의사항

## 작업 규칙

- 새 컴포넌트를 만들기 전에 비슷한 기존 구현을 검색한다.
- 전화번호는 저장 전에 `normalizePhone()`으로 숫자만 남긴다.
- 기존 migration을 수정하지 말고 새 migration을 생성한다.
- 요청과 관계없는 파일은 수정하지 않는다.

“좋은 코드를 작성한다”, “보안에 신경 쓴다”처럼 확인하기 어려운 말보다 구체적인 행동을 적는 편이 좋습니다.

반대로 다음 내용은 넣지 마세요.

• 코드 검색만으로 쉽게 알 수 있는 모든 파일과 함수의 목록
• 한 번만 수행할 작업의 긴 설명
• 이미 사용하지 않는 명령어와 오래된 구조
• 비밀번호, API 키와 고객 정보

/init으로 초안을 만들 수 있어요

프로젝트 폴더에서 클로드코드를 열고 /init을 실행하면 코드베이스를 분석해 CLAUDE.md 초안을 만들어줍니다.

/init

자동 생성된 초안은 출발점입니다. 클로드가 코드에서 발견한 기술 스택과 명령어는 잘 정리할 수 있지만, 왜 현재 방식을 선택했는지나 과거에 어떤 실수가 반복됐는지는 사람이 추가해야 해요.

처음에는 다음 정도로 작게 시작해도 충분합니다.

# 프로젝트 개요

예약 고객용 사이트와 내부 관리자 화면이 있는 프로젝트입니다.

## 구조

- `src/app`: 페이지와 API route
- `src/components`: 재사용 UI
- `src/lib`: 공용 로직과 외부 서비스 연동

## 명령어

- 개발: `npm run dev`
- 테스트: `npm test`
- 빌드: `npm run build`

## 규칙

- 새 코드를 만들기 전에 비슷한 기존 구현을 검색한다.
- 외부 패키지를 추가하기 전에 먼저 확인한다.
- 작업을 마치기 전에 관련 테스트와 빌드를 실행한다.

클로드가 같은 실수를 반복하거나 내가 같은 설명을 다시 입력하게 될 때 한 줄씩 보완하세요. 반대로 더 이상 사용하지 않는 규칙은 지워야 합니다.

한 줄로 정리하면

CLAUDE.md는 클로드코드의 머릿속에 프로젝트를 영구 저장하는 파일이 아닙니다. 새 세션마다 중요한 프로젝트 배경과 작업 규칙을 컨텍스트에 다시 올려주는 업무 설명서입니다.

짧고 구체적으로 작성하고, 코드에서 찾기 어려운 결정과 반복되는 실수를 중심으로 관리하세요. 그러면 매번 긴 프롬프트를 다시 쓰지 않아도 클로드코드가 프로젝트의 방식에 맞춰 작업을 시작할 수 있습니다.

직접 /init으로 파일을 만들고 프로젝트 규칙을 보완하는 순서는 바이브코딩 가이드 5장의 실습에서 따라 할 수 있습니다.