CLAUDE.md 작성법: 좋은 예시 템플릿과 넣을 것·뺄 것

새 대화를 열 때마다 같은 규칙을 다시 설명하고 있다면, 그 내용을 파일에 남겨볼 때입니다. CLAUDE.md는 Claude Code가 세션을 시작할 때 읽는 프로젝트 규칙 파일이에요. 2026년 9월 24일 기준 공식 메모리 문서는 이 파일을 "다시 설명해야 할 것을 적어 두는 자리"로 설명합니다. 빌드 명령, 폴더 구조, "항상 X를 하라"는 규칙처럼 매 세션에 필요한 사실만 넣고 파일 하나를 200줄 아래로 유지하는 것이 핵심입니다.

이 글에서는 파일을 어디에 두는지, 무엇을 넣고 뺄지, 바로 복사해 고쳐 쓸 수 있는 예시 템플릿까지 순서대로 정리합니다. CLAUDE.md라는 개념 자체가 처음이라면 에이전트 메모리 파일 뜻과 쓰임을 먼저 읽어도 좋습니다.

길게 쓴다고 더 잘 따르는 건 아니에요

새 세션에서 지난 대화의 지시가 모두 이어질 거라고 기대하면 빠지는 내용이 생길 수 있습니다. "테스트는 npm test로 돌려"처럼 계속 필요한 지시는 파일에 적어두는 편이 분명해요. CLAUDE.md는 세션이 열릴 때 컨텍스트 창에 그대로 실립니다. 그래서 규칙이 길어지면 읽는 데 드는 토큰도 늘고 정말 중요한 지시가 묻힐 수 있습니다. 공식 문서는 긴 파일이 컨텍스트를 더 쓰고 지시를 따르는 정도(adherence)도 떨어뜨린다고 설명합니다.

문서가 제안하는 추가 시점은 네 가지입니다.

• Claude가 같은 실수를 두 번째 했을 때
• 코드 리뷰에서 "이 코드베이스에선 원래 이렇게 한다"가 나왔을 때
• 지난 세션에 쳤던 정정을 이번 세션에 또 치고 있을 때
• 새 팀원에게도 똑같이 설명해야 할 내용일 때

나만 쓸 규칙인지, 함께 쓸 규칙인지

파일끼리 서로 덮어쓰지는 않습니다. 찾은 파일은 모두 이어 붙여서 컨텍스트에 들어가요. 표의 위쪽(넓은 범위)부터 읽히고 실행한 폴더에 가까운 파일일수록 나중에 읽힙니다. 같은 폴더에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙습니다.

• 실행한 폴더와 그 위 폴더들의 CLAUDE.md·CLAUDE.local.md는 시작할 때 로드됩니다.
• 하위 폴더의 CLAUDE.md는 Claude가 그 폴더의 파일을 읽을 때 따라 들어옵니다.
• 로드됐는지 확인하려면 세션에서 /context를 치고 Memory files 목록을 봅니다.

CLAUDE.local.md는 git worktree를 여러 개 쓰면 만든 worktree에만 있다는 점도 알아두세요. 여러 worktree에서 같은 개인 규칙을 쓰고 싶다면 홈 폴더의 파일을 @~/.claude/my-project-instructions.md처럼 임포트하는 방법을 문서가 안내합니다.

시작은 /init

빈 파일에서 시작하지 않아도 됩니다. /init을 실행하면 Claude가 코드베이스를 분석해 빌드 명령·테스트 방법·컨벤션이 담긴 초안을 만듭니다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안해요. .cursor/rules/나 .github/copilot-instructions.md 같은 다른 도구의 규칙 파일이 있으면 관련 내용을 초안에 반영합니다.

실행 전에 환경 변수 CLAUDE_CODE_NEW_INIT=1을 설정하면 질문을 주고받는 여러 단계 흐름으로 바뀝니다. CLAUDE.md뿐 아니라 스킬과 훅까지 무엇을 준비할지 묻고 파일을 쓰기 전에 검토할 제안을 먼저 보여 줍니다.

초안이 나오면 Claude가 스스로 알아낼 수 없는 것만 덧붙입니다. 예를 들어 "결제 코드는 반드시 plan 모드로 먼저 계획한다" 같은 팀 규칙입니다.

넣을 것과 뺄 것 체크리스트

공식 모범 사례 문서는 한 줄마다 "이 줄을 지우면 Claude가 실수할까?"라고 물어보고, 아니라면 지우라고 권합니다. 문서의 표를 옮기면 다음과 같아요.

실제로 확인할 수 있게 적어주세요

"잘해줘"라고 적는 것보다 무엇을 하면 잘한 것인지 적어주는 편이 낫습니다. 공식 문서도 다음과 같은 차이를 예로 듭니다.

1. 구체성: 검증 가능한 문장으로 씁니다.
2. 구조: 마크다운 헤더와 불릿으로 묶습니다. 관련 규칙끼리 모아두면 Claude도 사람처럼 필요한 부분을 찾기 쉬워집니다.
3. 일관성: 두 규칙이 충돌하면 Claude가 임의로 하나를 고를 수 있습니다. 상위 폴더 CLAUDE.md, 하위 폴더 파일, .claude/rules/까지 주기적으로 모순을 정리합니다.
4. 강조는 한 줄에만: 유독 한 규칙을 계속 건너뛴다면 그 줄에만 "IMPORTANT" 같은 강조를 붙입니다. 여러 줄을 강조하면 어느 것도 눈에 띄지 않는다고 문서는 설명합니다.

복사해서 고쳐 쓰는 예시 템플릿

아래는 가상의 프로젝트를 가정한 예시입니다. 명령과 경로는 내 프로젝트에 맞게 바꿔서 쓰세요. 공식 문서는 정해진 형식이 없다고 하니 제목 구성도 자유롭게 바꿔도 됩니다.

# 프로젝트 개요

- 동네 공방 수업 예약 웹앱(예시). Next.js + TypeScript
- 화면은 `app/`, 공용 컴포넌트는 `components/`, DB 접근은 `lib/db/`에만 둔다

# 명령

- 개발 서버: `npm run dev`
- 테스트: `npm test` (한 파일만 돌릴 때는 `npm test -- 파일경로`)
- 커밋 전에 `npm run lint`와 `npm run typecheck`를 실행한다

# 코드 규칙

- 2칸 들여쓰기, ES 모듈(import/export)을 쓴다
- 날짜는 항상 `lib/date.ts`의 함수로 다룬다(시간대 버그 방지)

# 작업 방식

- 결제 관련 코드(`lib/payments/`)는 plan 모드로 먼저 계획을 보여 준 뒤 수정한다
- 브랜치 이름은 `feat/짧은-설명` 형식

# 하지 말 것

- `.env*` 파일은 읽거나 수정하지 않는다
- 마이그레이션 파일은 새로 만들기만 하고 기존 파일은 고치지 않는다

코드가 많은 프로젝트에만 필요한 파일은 아닙니다. 강의 자료나 블로그 초안을 정리하는 폴더라면 이 정도로도 충분해요.

# 이 프로젝트

- 목적: 주간 뉴스레터 초안을 만드는 폴더
- 글은 `drafts/`에, 완성본은 `published/`에 둔다
- 문체: 존댓말, 한 문장 30자 안팎, 영어 약어는 처음 나올 때 풀어 쓴다
- 외부 사실은 반드시 출처 URL을 같은 줄에 적는다

# 하지 말 것

- `published/` 안의 파일은 수정하지 않는다
- 이메일·전화번호 같은 개인정보를 예시로 만들지 않는다

길어지면 나누는 방법

규칙이 계속 늘어나면 무조건 줄이기보다 언제 필요한 내용인지 나눠보세요.

• 특정 폴더·파일에만 해당하는 규칙: .claude/rules/ 아래 주제별 .md 파일로 옮기고 맨 위에 paths 프런트매터를 붙입니다. 그러면 Claude가 해당 패턴의 파일을 읽을 때만 로드됩니다. paths가 없는 규칙 파일은 .claude/CLAUDE.md와 똑같이 시작할 때 로드돼요. 모든 프로젝트에 쓰는 개인 규칙은 ~/.claude/rules/에 둘 수 있습니다.
• 여러 단계 절차나 가끔 쓰는 지식: 스킬로 뺍니다. 평소에는 스킬 설명만 컨텍스트에 있고 본문은 실제로 쓸 때 로드됩니다.
• 다른 문서를 그대로 끌어올 때: @docs/git-instructions.md처럼 @경로 임포트를 씁니다. 상대 경로는 임포트하는 파일 기준이고 임포트는 최대 4단계까지 이어집니다. 백틱으로 감싼 `@README`는 임포트되지 않고 글자로 남아요. 임포트한 파일도 세션 시작 시 함께 로드되므로 정리에는 도움이 되지만 컨텍스트 절약 효과는 없습니다.

---
paths:
  - "src/api/**/*.ts"
---

# API 규칙

- 모든 API 엔드포인트는 입력값 검증을 포함한다
- 오류 응답은 공통 형식을 쓴다

체크인된 CLAUDE.md라면 /doctor 점검이 코드에서 알 수 있는 내용(폴더 구조, 의존성 목록 등)을 잘라내자는 제안도 해 줍니다(Claude Code v2.1.206 이상).

자주 하는 실수

• AGENTS.md와 CLAUDE.md가 둘 다 있는데 AGENTS.md 내용을 모른다. Claude Code v2.1.277 이상은 CLAUDE.md나 CLAUDE.local.md가 없을 때 AGENTS.md를 직접 읽습니다. 반대로 둘 중 하나라도 있으면 기본 설정에서는 CLAUDE.md 쪽만 읽어요. 두 도구가 같은 규칙을 보게 하려면 CLAUDE.md 맨 위에 @AGENTS.md 한 줄을 두고 그 아래에 Claude 전용 규칙을 적습니다. /config의 Project instructions를 claude-md-and-agents-md로 바꿔 둘 다 읽게 하는 방법도 있습니다.
• 지켜지지 않는 규칙을 계속 늘린다. CLAUDE.md는 안내이지 강제가 아닙니다. "커밋 전 반드시 lint"처럼 특정 시점에 꼭 실행돼야 하는 것은 훅으로 옮깁니다. 어떤 행동을 무조건 막아야 한다면 PreToolUse 훅을 쓰라고 문서는 안내합니다.
• HTML 주석에 메모를 남기며 토큰을 걱정한다. <!-- --> 블록 주석은 컨텍스트에 들어가기 전에 제거됩니다. 유지보수 메모는 남겨도 됩니다. 단, 코드 블록 안의 주석은 그대로 남아요.
• /compact 뒤에 규칙이 사라진 것 같다. 프로젝트 루트 CLAUDE.md는 압축 후 디스크에서 다시 읽힙니다. 하위 폴더 CLAUDE.md와 paths 규칙은 해당 파일을 다시 읽을 때 돌아와요. 그 외에 사라진 것은 대화 중에만 말했던 지시입니다. 그런 지시는 파일로 옮깁니다.

자동 메모리와의 차이

한편 Claude가 스스로 남기는 auto memory도 있습니다. 이름이 비슷해서 헷갈릴 수 있는데요. Claude가 사용자의 정정과 선호를 ~/.claude/projects/<project>/memory/에 적어 두는 기능이고 기본값이 켜져 있습니다. CLAUDE.md는 사람이 쓰는 규칙, auto memory는 Claude가 쓰는 학습 노트예요.

• 매 세션 시작 시 MEMORY.md 색인의 앞 200줄 또는 25KB 중 먼저 닿는 만큼만 로드되고, 세부 주제 파일은 필요할 때 읽습니다.
• 같은 git 저장소의 worktree끼리는 공유되지만 다른 기기와는 공유되지 않습니다.
• "항상 pnpm을 써"처럼 기억하라고 말하면 auto memory로 갑니다. 규칙 파일에 넣고 싶으면 "CLAUDE.md에 추가해"라고 말하거나 /memory로 직접 엽니다. /memory에서는 auto memory를 끄고 켜거나 저장된 메모를 열어볼 수도 있어요.

다음 단계

• 에이전트 메모리 파일(CLAUDE.md·AGENTS.md) 뜻과 쓰임
• Claude Code 사용법: 처음 세션에서 익힐 6가지
• MCP, Skills, 서브에이전트 차이
• Claude Code 비용 줄이는 7가지
• 다음에 배울 내용은 강의 소개에서 확인할 수 있습니다.

출처와 확인 (2026-09-24)

• How Claude remembers your project (CLAUDE.md 위치·로드 순서, 임포트, .claude/rules/, AGENTS.md, auto memory, /memory)
• Best practices for Claude Code (넣을 것·뺄 것 표, 강조, /doctor 정리 제안)
• Manage costs effectively (CLAUDE.md 200줄 권장, 절차는 스킬로)
• Extend Claude with skills (스킬 본문은 쓸 때만 로드)
• Hooks guide (정해진 시점에 반드시 실행)
• Commands (/init, /memory, /context, /doctor)