CLAUDE.md 작성법: 클로드 코드가 내 프로젝트를 제대로 이해하게 만드는 법

클로드 코드를 좀 써보면 이런 순간이 온다. 분명 어제와 같은 질문인데 오늘은 엉뚱한 파일을 건드리고, 우리 프로젝트에서 쓰지도 않는 라이브러리를 갖다 붙인다. 원인은 대개 하나다. 내 프로젝트가 어떻게 굴러가는지를 AI가 모른다는 것. 이걸 풀어주는 열쇠가 CLAUDE.md다. 이 파일을 처음부터 어떻게 쓰는지, 왜 이 한 장이 결과 품질을 좌우하는지 짚어본다. 잘 쓴 파일과 못 쓴 파일은 뭐가 다른지, 실제로 도움이 되려면 무엇을 넣어야 하는지도 차례로 정리했다.

CLAUDE.md가 대체 뭐길래

CLAUDE.md는 클로드 코드가 세션을 시작할 때 자동으로 읽어들이는 프로젝트 안내문이다. 새로 온 팀원에게 “우리 코드는 이런 규칙으로 짜고, 빌드는 이렇게 하고, 여긴 절대 손대지 마세요”라고 브리핑하는 것과 똑같다. 다른 점은 하나뿐이다. 그 브리핑을 매 대화 첫머리마다 알아서 대신 해준다는 것.

짚어둘 게 있다. CLAUDE.md에 적은 내용은 어딘가 참고 문서로 저장돼 있다 필요할 때 열리는 게 아니다. 세션이 열리는 순간 대화 맥락(컨텍스트)으로 곧장 실려 들어간다. 그래서 “알아두면 좋은 정보”라기보다 AI가 읽고 따르려 하는 지시에 가깝게 작동한다. 다만 이걸 강제 설정으로 오해하면 안 된다. 어디까지나 참고 맥락이다. 공식 문서도 시스템 프롬프트가 아니라 그 뒤에 붙는 메시지 형태로 전달된다고 설명한다. 반드시 지켜진다는 보장은 없다. 무슨 일이 있어도 못 하게 막아야 하는 동작이라면 CLAUDE.md 문장이 아니라 훅(hook) 같은 강제 수단을 써야 한다. 그래도 실무 체감으로는, 루트에 이 파일 하나만 잘 놔둬도 매번 “우리는 pnpm 써”, “테스트는 vitest야”, “이 폴더는 건드리지 마”를 반복해서 타이핑할 일이 거의 사라진다.

CLAUDE.md 생성, 작성, 로드 확인 3단계 흐름도 — CLAUDE.md 만들기 3단계

파일은 어디에 두나

가장 기본은 프로젝트 루트에 CLAUDE.md를 만드는 것이다. .claude/CLAUDE.md에 둬도 똑같이 프로젝트 지시로 잡히니 편한 쪽을 쓰면 그만이다. 클로드 코드는 현재 작업 디렉터리에서 위쪽으로 거슬러 올라가며 이 파일을 찾는데, 상위 경로에서 발견한 CLAUDE.md는 세션이 열릴 때 통째로 읽힌다. 하위 폴더에 둔 CLAUDE.md는 좀 다르게 움직인다. 처음부터 읽지 않고, 클로드가 그 폴더 안의 파일을 실제로 열어볼 때 그제서야 딸려 들어온다. 모노레포라면 공통 규칙은 루트에, 패키지별 세부 규칙은 각 패키지 폴더에 나눠 두는 방식이 꽤 잘 맞는다.

내 계정 전체에 걸고 싶은 개인 규칙, 이를테면 “설명은 항상 한국어로” 같은 건 ~/.claude/CLAUDE.md에 두면 모든 프로젝트에 공통으로 먹는다. 반대로 이 프로젝트에서만 쓰고 커밋은 하기 싫은 임시 메모라면 CLAUDE.local.md로 만들어 .gitignore에 넣으면 된다. 팀 공유 규칙과 개인 취향을 갈라두는 흔한 방법이다. 한 가지, 여러 워크트리를 오가며 작업한다면 CLAUDE.local.md는 만든 워크트리에만 남는다. 이럴 땐 홈 디렉터리에 파일을 두고 CLAUDE.md 안에서 @~/.claude/내-메모.md처럼 불러오는 편이 낫다.

파일을 잘게 쪼개고 싶을 때 알아두면 좋은 게 있다. CLAUDE.md 안에서 @경로/파일.md 형식으로 다른 문서를 끌어올 수 있다. 가령 @docs/git-workflow.md 한 줄이면 그 파일 내용이 통째로 맥락에 합쳐진다. 다만 이렇게 나눠도 세션 시작 때 결국 다 읽히므로 토큰이 절약되지는 않는다. 순전히 정리하고 관리하기 편하자는 목적이다.

CLAUDE.md 작성법: 무엇을 넣어야 하나

빈 파일 앞에서 막막하다면 클로드 코드에서 /init 명령을 먼저 돌려보자. 프로젝트 구조를 훑어 CLAUDE.md 초안을 자동으로 만들어준다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안하는 식이라 부담도 없다. 여기서 시작해 손으로 다듬는 게 가장 빠르다. 다만 자동 생성본은 대체로 장황하다. 실제로 지키게 할 핵심만 남기고 과감히 덜어내는 편이 낫다.

넣으면 효과가 큰 항목을 아래 표로 정리했다. 전부 채울 필요는 없고 프로젝트 성격에 맞는 것부터 골라 담으면 충분하다.

항목	왜 넣나	예시
빌드·실행 명령	AI가 검증 없이 추측하지 않게	빌드는 `pnpm build`, 개발서버 `pnpm dev`
테스트 방법	수정 후 스스로 검증하게	테스트는 `pnpm test`, 단일 파일은 `vitest run 경로`
코드 스타일	기존 컨벤션과 어긋난 코드 방지	세미콜론 없음, 함수형 컴포넌트만, named export 선호
기술 스택	엉뚱한 라이브러리 도입 차단	React 19 + TypeScript, 상태관리는 Zustand
디렉터리 규칙	파일을 엉뚱한 곳에 만들지 않게	공통 UI는 `src/components/ui`, API는 `src/api`
절대 금지 사항	사고 예방(가장 중요)	`db/migrations` 수정 금지, main 직접 커밋 금지

특히 마지막 “절대 금지 사항”은 나는 제일 위쪽에 둔다. 하지 말아야 할 일을 못 박아두면, AI가 좋은 의도로 벌이는 사고를 상당 부분 막을 수 있다.

좋은 예시 vs 나쁜 예시

같은 내용이라도 어떻게 쓰느냐에 따라 효과가 크게 갈린다. 나쁜 예시부터 보자.

# 프로젝트 안내
이 프로젝트는 좋은 코드 품질을 유지하는 것이 중요합니다.
깔끔하고 읽기 쉬운 코드를 작성해 주세요.
모범 사례를 따르고 적절한 테스트를 작성하세요.

틀린 말은 하나도 없다. 문제는 AI가 실행할 만한 정보가 없다는 것이다. “좋은 코드”, “모범 사례”는 사람에게도 애매하다. 반면 좋은 예시는 구체적이고 검증할 수 있다.

# 우리 프로젝트

## 명령어
- 빌드: pnpm build
- 테스트: pnpm test (수정 후 반드시 실행)
- 린트: pnpm lint

## 규칙
- 컴포넌트는 함수형만, 파일당 하나
- 새 의존성 추가 전에 먼저 물어볼 것
- src/legacy/ 는 읽기 전용, 수정 금지

## 스타일
- 세미콜론 없음(prettier 설정 따름)
- import는 절대경로(@/) 사용

차이가 보이는가. 좋은 CLAUDE.md는 명령어와 규칙이 명령형으로 딱 떨어진다. “~하면 좋습니다” 대신 “~할 것”, “~ 금지”로 쓴다. 공식 가이드도 같은 얘기를 한다. “코드를 잘 정리하세요”보다 “API 핸들러는 src/api/handlers/에 둔다”처럼 검증할 수 있게 쓰라는 것이다. 그래야 AI가 판단이 아니라 실행을 한다.

여러 프로젝트에 직접 써보고 느낀 게 있다. CLAUDE.md는 짧을수록 잘 지켜진다. 처음엔 욕심이 나서 코딩 철학이며 아키텍처 설명이며 잔뜩 적었는데, 정작 “이 폴더 건드리지 마” 같은 정말 중요한 지시가 긴 문장 속에 파묻혀 무시되기 일쑤였다. 공식 문서도 한 파일당 200줄 안쪽을 권한다. 나는 A4 한 장을 넘기지 않는 걸 기준으로 삼는다. 상세한 설명이 필요하면 별도 md로 빼고, CLAUDE.md에는 @docs/architecture.md처럼 불러오기 한 줄만 걸어두는 식이 훨씬 잘 먹힌다.

실전 적용 단계

처음 도입할 때 이 순서를 따르면 무난하다.

프로젝트 루트에서 클로드 코드를 실행하고 /init으로 초안을 생성한다.
생성된 CLAUDE.md에서 뻔한 일반론은 지우고, 빌드·테스트 명령을 실제 우리 것으로 고친다.
파일 맨 위에 “절대 금지 사항” 섹션을 만들어 건드리면 안 되는 폴더·브랜치를 못 박는다.
실제로 몇 번 작업을 시켜보고, AI가 자꾸 틀리는 지점이 나올 때마다 한 줄씩 규칙을 추가한다.
제대로 실려 있는지 세션에서 /context를 쳐 Memory files 목록에 파일이 뜨는지 확인한다.
팀 공유용이면 커밋하고, 개인 메모는 CLAUDE.local.md로 분리한다.

4번이 핵심이다. CLAUDE.md는 한 번 쓰고 끝나는 문서가 아니라 AI가 실수할 때마다 자라는 문서다. “아 또 이걸 틀리네” 싶은 순간이 규칙 한 줄을 보탤 타이밍이다. 손으로 열어 고쳐도 되고, 대화 중에 “이거 CLAUDE.md에 추가해줘”라고 시켜도 된다. 참고로 클로드 코드에는 이와 별개로 대화 중 교정 내용을 스스로 메모해두는 자동 메모리 기능도 있다. 다만 이쪽은 AI가 알아서 쌓는 것이라, 내가 규칙으로 못 박고 싶은 건 결국 CLAUDE.md에 직접 적어야 한다. 이렇게 몇 주만 다듬으면 반복되는 실수가 눈에 띄게 준다.

주의할 점

내용을 무한정 늘리면 오히려 역효과다. 매 세션 통째로 실려 토큰을 잡아먹는 데다, 길수록 정작 중요한 지시의 밀도가 떨어진다. 파일이 자꾸 비대해진다면 특정 폴더나 확장자에서만 읽히는 규칙 파일(.claude/rules/)로 쪼개두는 방법도 있다. 그러면 관련 파일을 만질 때만 그 규칙이 올라오니 평소 맥락이 가벼워진다. 무엇보다 민감정보는 절대 넣지 말자. API 키나 비밀번호를 CLAUDE.md에 적으면 커밋과 동시에 유출된다. 그런 값은 .env에 두고 “환경변수는 .env 참고”라고만 안내하면 충분하다.

자주 묻는 질문

CLAUDE.md 파일 이름을 소문자로 써도 되나요?

대소문자를 정확히 맞춰 CLAUDE.md로 쓰길 권한다. 공식 문서 표기가 전부 대문자이고, 파일명을 다르게 하면 자동으로 읽히지 않을 수 있다. 표기를 그대로 따르는 편이 안전하다.

기존 README.md가 있으면 그걸 대신 읽나요?

클로드 코드는 CLAUDE.md를 읽지, README를 지시로 삼지 않는다. README는 사람 독자를 위한 소개문이고 CLAUDE.md는 AI에게 주는 작업 지시라 목적 자체가 다르다. 정 README 내용을 활용하고 싶으면 CLAUDE.md 안에 @README.md로 불러오면 된다. 다른 AI 도구용으로 쓰던 AGENTS.md가 이미 있다면 이 역시 @AGENTS.md 한 줄로 함께 읽히게 할 수 있다.

규칙을 적었는데도 AI가 안 지켜요.

먼저 문장이 애매하거나 파일이 너무 길지 않은지 보자. “깔끔하게”처럼 해석의 여지가 있는 표현은 “세미콜론 없음”처럼 검증 가능한 지시로 바꾸고, 정말 중요한 금지 사항은 위쪽으로 올린다. /context로 파일이 실제 로드됐는지 확인하는 것도 기본이다. 다만 CLAUDE.md는 강제 설정이 아니라 참고 맥락이라 100% 준수를 보장하지는 않는다. 커밋 직전처럼 특정 시점에 무조건 실행돼야 하는 규칙이라면 문장으로 적기보다 훅(hook)으로 거는 게 확실하다.

여러 폴더에 CLAUDE.md를 두면 충돌하나요?

덮어쓰기가 아니라 합쳐진다. 상위 경로의 파일은 세션 시작 때 전부 읽히고, 하위 폴더 파일은 그 안의 파일을 열 때 딸려 온다. 모노레포에서 공통 규칙은 루트에, 패키지별 규칙은 해당 폴더에 나눠 두면 맥락이 자연스럽게 이어진다. 단, 서로 모순되는 규칙이 여기저기 흩어져 있으면 AI가 그중 하나를 임의로 고를 수 있으니, 상충하는 지시가 없도록 가끔 정리해주는 게 좋다.

CLAUDE.md는 거창한 설정 파일이 아니다. AI에게 우리 프로젝트를 브리핑하는 한 장짜리 메모에 가깝다. 그런데 이 한 장이 있으면, 매번 같은 설명을 되풀이하는 대신 처음부터 우리 방식대로 일하는 파트너를 얻는다. 지금 작업 중인 프로젝트 루트에서 /init부터 한번 돌려보자.

공식 참고: Claude Code 메모리(CLAUDE.md) 공식 문서

클로드 코드를 처음 설치하고 세팅하는 과정이 궁금하다면 클로드 코드 설치와 기본 사용법 가이드를 먼저 읽어보자. 터미널 기반 AI 코딩 도구를 비교해보고 싶다면 Codex CLI 설치와 설정 정리도 함께 참고하면 좋다.