이 장의 내용 · 7
Claude Code는 새 대화를 시작할 때마다 기억이 비어 있습니다. 어제 "답은 존댓말로 해 줘", "커밋 전에 테스트 돌려 줘"라고 했어도, 오늘 새로 켜면 모릅니다. 매번 같은 설명을 반복해야 할까요?
그래서 CLAUDE.md가 있습니다. 프로젝트 폴더에 두는 안내서로, Claude Code가 대화를 시작할 때마다 가장 먼저 읽습니다. 한 번 적어 두면 매번 말하지 않아도 됩니다.
4.1어디에 두나요?
./CLAUDE.md 이 프로젝트의 규칙 (팀과 함께 씀)
~/.claude/CLAUDE.md 내 모든 프로젝트에 쓰는 개인 규칙
./CLAUDE.local.md 이 프로젝트의 내 개인 메모 (Git에 올리지 않음)- 프로젝트 CLAUDE.md는 Git10장에 함께 올려 팀원과 나눕니다.
- 사용자 전역 파일(~/.claude/CLAUDE.md)은 나만의 습관을 적는 곳입니다. 어느 프로젝트를 열어도 적용됩니다.
- 여러 파일이 있으면 서로 덮어쓰지 않고 모두 합쳐서 읽습니다. 그러니 서로 어긋나는 규칙이 없게 하세요.
4.2처음 만들기: /init
Claude Code 안에서 /init 을 입력하면, AI가 프로젝트를 둘러보고 실행 명령, 테스트 방법, 코드 규칙을 찾아 CLAUDE.md 초안을 써 줍니다. 이미 파일이 있으면 덮어쓰지 않고 고칠 점을 제안합니다.
언제 하면 좋을까요? /init 은 프로젝트에 있는 파일을 보고 초안을 쓰기 때문에, 빈 폴더에서 하면 적을 내용이 거의 없습니다. 이 순서를 추천합니다.
- 1단계: PRD6장로 무엇을 만들지 정합니다.
- 2단계: Claude Code에게 프로젝트 뼈대를 만들게 합니다. 예: "Next.js로 새 프로젝트 만들어 줘"
- 3단계: 뼈대가 생기면 /init 으로 CLAUDE.md 초안을 만듭니다.
- 4단계: 기능을 만들다가 같은 설명을 두 번 하게 되면 그때마다 추가합니다.
프로젝트 구조가 크게 바뀌었을 때 /init 을 다시 실행하면, 지금 파일을 바탕으로 고칠 점을 제안해 줍니다.
초안을 받은 뒤에는, AI가 코드만 보고는 알 수 없는 것을 직접 보태세요. "왜 이렇게 하는지", "하면 안 되는 것" 같은 내용입니다.
4.3무엇을 적을까요?
공식 문서의 기준은 간단합니다. "같은 설명을 두 번째 하게 되면 적는다."
- 실행 명령: "테스트는 npm test, 개발 서버는 npm run dev"
- 규칙: "커밋 전에 npm run qa 실행", "답은 항상 존댓말"
- 구조: "API 코드는 src/api 에 둔다"
- 함정: "이 프로젝트의 Next.js는 최신 버전이라 옛날 방식과 다르다"
4.4짧게 유지하기
CLAUDE.md는 매 대화마다 통째로 읽히기 때문에 길수록 AI의 집중력이 흐려집니다. 공식 문서는 파일 하나를 200줄 이내로 권합니다.
- 여러 단계로 된 절차(배포 순서 등)는 스킬9장로 옮기세요. 필요할 때만 읽힙니다.
- 다른 파일을 불러올 수도 있습니다. @README 처럼 @ 뒤에 파일 경로를 쓰면 그 파일 내용이 함께 읽힙니다.
- "반드시 매번" 지켜야 하는 검사는 CLAUDE.md보다 훅(hook)이 확실합니다. CLAUDE.md는 안내이고, 훅은 자동으로 실행되는 장치입니다.
4.5바이브공장장 홈페이지의 실제 예
이 홈페이지의 루트 CLAUDE.md는 짧습니다. 핵심만 줄이면 이렇습니다.
@AGENTS.md
# 작업 흐름
- 에이전트: layout-designer(디자인) → frontend / backend(구현) → qa(검증)
- 코드를 바꾸면 보고 전에 qa 에이전트를 자동으로 실행
- 자동 점검 3단계: 응답 끝날 때 / 커밋 전 / 푸시 후첫 줄 @AGENTS.md 는 다른 AI 도구와 함께 쓰는 안내 파일을 불러옵니다. 그리고 운영자의 개인 전역 파일(~/.claude/CLAUDE.md)에는 "항상 존댓말로 답한다" 한 줄이 들어 있습니다. 그래서 어느 프로젝트를 열어도 AI가 존댓말로 답합니다.
4.6잘 안 지켜질 때
- /context 를 입력하면 지금 읽힌 파일 목록이 보입니다. 내 CLAUDE.md가 빠져 있지 않은지 확인하세요.
- 규칙을 더 구체적으로 바꾸고, 서로 부딪치는 규칙이 없는지 살펴보세요.
- /memory 로 파일을 바로 열어 고칠 수 있습니다.
4.7AI에게 이렇게 말해 보세요
- “CLAUDE.md를 한국어로 바꾸고, 우리가 정한 규칙도 추가해 줘”
- “방금 알려 준 규칙을 CLAUDE.md에 추가해 줘”
- “CLAUDE.md에 오래됐거나 서로 부딪치는 규칙이 없는지 점검해 줘”
CLAUDE.md가 "어떻게 일할지"를 알려 준다면, 이제 "무엇을 해 달라고" 잘 말하는 법이 남았습니다. 5장에서는 프롬프트 기본기를 알아보겠습니다.
— 4장 끝 —