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

CLAUDE.md 작성법의 핵심은 Claude가 코드만 읽고는 알 수 없는 것(테스트·빌드 명령, 헷갈리게 생긴 코드, 저장소 밖에서 정한 규칙, 두 번 고쳐 준 실수)만 적고 파일 하나를 200줄 아래로 두는 것입니다. CLAUDE.md는 Claude Code가 세션을 시작할 때마다 읽는 프로젝트 규칙 파일이고, 보통 프로젝트 맨 위 폴더에 CLAUDE.md로 두며 /init으로 초안을 만들 수 있어요. 꼭 지켜야 하는 규칙은 CLAUDE.md에 강조를 더하는 대신 훅으로 옮기라는 것이 지금의 공식 권장입니다(확인일 2026-10-30, 공식 메모리 문서·모범 사례 문서 기준).

새 대화를 열 때마다 같은 규칙을 다시 설명하고 있다면, 그 내용을 파일에 남겨볼 때입니다. 공식 메모리 문서는 이 파일을 "다시 설명해야 할 것을 적어 두는 자리"로 설명합니다.

CLAUDE.md 작성 순서 다섯 단계

1. 프로젝트 폴더에서 claude를 열고 /init을 실행합니다. Claude가 코드를 읽고 명령·테스트 방법·컨벤션이 담긴 초안을 만듭니다.
2. 초안에서 코드를 읽으면 알 수 있는 줄을 지웁니다. 폴더 구조 설명, 의존성 목록, 아키텍처 개요가 여기에 해당합니다.
3. Claude가 스스로 알 수 없는 것만 덧붙입니다. 확인 명령, 따라 하면 안 되는 옛 코드, 팀이 정한 규칙, 두 번 고쳐 준 실수입니다.
4. 세션에서 /context를 입력해 Memory files 목록에 파일이 보이는지 확인합니다.
5. 쓰면서 다듬습니다. 같은 실수가 두 번 나오면 한 줄 추가하고, 200줄이 넘으면 .claude/rules/나 스킬로 나누고, 예외 없이 지켜야 하는 규칙은 훅으로 옮깁니다.

아래에서 파일 위치, 넣을 것과 뺄 것, 바로 복사해 고쳐 쓸 수 있는 예시 템플릿을 차례로 정리했습니다. 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.md가 모든 세션에 실리기 때문에 모든 줄이 매번 Claude의 주의를 조금씩 쓴다고 설명합니다. 그래서 Claude가 코드만 보고는 알 수 없는 것만 남기라고 해요. 문서가 꼽은 넣을 것과, 메모리 문서의 /doctor 설명에 나온 뺄 것을 표로 옮기면 이렇습니다.

2026년 10월 30일 기준 모범 사례 문서는 "CLAUDE.md에 아키텍처와 파일 배치를 설명하라"를 이제 버려도 되는 옛 조언으로 분류합니다. Claude가 저장소를 직접 읽기 때문이에요.

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

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

1. 구체성: 검증 가능한 문장으로 씁니다.
2. 구조: 마크다운 헤더와 불릿으로 묶습니다. 관련 규칙끼리 모아두면 Claude도 사람처럼 필요한 부분을 찾기 쉬워집니다.
3. 일관성: 두 규칙이 충돌하면 Claude가 임의로 하나를 고를 수 있습니다. 상위 폴더 CLAUDE.md, 하위 폴더 파일, .claude/rules/까지 주기적으로 모순을 정리합니다.
4. 강조 대신 훅: 한 규칙을 계속 건너뛴다고 "IMPORTANT"나 대문자 강조를 붙여도 대개 해결되지 않는다고 모범 사례 문서는 설명합니다. 지금 모델은 평범하게 쓴 한 줄도 따르고, 강조를 쌓으면 그 규칙을 지나치게 적용하기 쉽다고 해요. 파일이 길어서 그 줄이 묻힌 거라면 파일을 줄이고, 예외 없이 지켜야 하는 규칙이라면 훅이나 권한의 deny 규칙으로 옮깁니다.

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

아래는 가상의 프로젝트(동네 공방 수업 예약 웹앱)를 가정한 예시입니다. 명령과 경로는 내 프로젝트에 맞게 바꿔서 쓰세요. 프로젝트 소개나 폴더 구조는 Claude가 코드에서 읽을 수 있어서 넣지 않았습니다. 공식 문서는 정해진 형식이 없다고 하니 제목 구성도 자유롭게 바꿔도 됩니다.

# 명령

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

# 코드 규칙

- 2칸 들여쓰기, ES 모듈(import/export)을 쓴다
- 날짜는 항상 `lib/date.ts`의 함수로 다룬다(시간대 버그 방지)
- DB 접근은 `lib/db/`의 함수로만 한다(화면 코드에서 직접 쿼리하지 않는다)
- `lib/legacy/`는 아직 쓰이지만 새 코드에서 그 방식을 따라 하지 않는다

# 작업 방식

- 결제 관련 코드(`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 점검이 코드에서 알 수 있는 내용(폴더 구조, 의존성 목록, 아키텍처 개요)을 잘라내자고 제안합니다. /doctor prompt-audit(Claude Code v2.1.283 이상)는 옛 모델용으로 쓴 지시, 없는 파일을 가리키는 줄, 서로 부딪히는 규칙을 찾아 수정안을 보여 줍니다. 파일은 내가 적용하라고 할 때만 바뀝니다.

자주 하는 실수

• 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 훅이나 권한의 deny 규칙을 씁니다.
• 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는 어디에 만들어야 하나요?

팀과 함께 쓸 규칙은 프로젝트 맨 위 폴더의 ./CLAUDE.md(또는 ./.claude/CLAUDE.md)에 둡니다. 모든 프로젝트에 쓰는 내 취향은 ~/.claude/CLAUDE.md, 이 프로젝트에서 나만 쓸 메모는 ./CLAUDE.local.md에 두고 .gitignore에 추가합니다.

CLAUDE.md는 몇 줄까지 써도 되나요?

공식 메모리 문서는 파일 하나를 200줄 아래로 두라고 권합니다. 길어지면 컨텍스트를 더 쓰고 지시를 따르는 정도도 떨어진다고 해요. 권장 길이를 넘으면 시작할 때와 /status에서 경고가 뜨고, 4MiB가 넘는 파일은 아예 건너뜁니다.

AGENTS.md가 이미 있으면 CLAUDE.md를 따로 써야 하나요?

꼭 그렇지는 않습니다. Claude Code v2.1.277 이상은 CLAUDE.md·CLAUDE.local.md가 없을 때 AGENTS.md를 그대로 읽습니다. Claude 전용 규칙을 더하고 싶으면 CLAUDE.md 맨 위에 @AGENTS.md를 적고 그 아래에 덧붙입니다.

CLAUDE.md에 적었는데 Claude가 자꾸 무시해요

먼저 /context에서 파일이 로드됐는지 봅니다. 로드됐는데도 놓친다면 파일이 길어서 묻혔을 가능성이 크니 줄이고, 예외 없이 지켜야 하는 규칙이면 훅으로 옮깁니다. "IMPORTANT"를 더 붙이는 건 지금 모델에서는 해결책이 아니라고 모범 사례 문서는 설명합니다.

다음 단계

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

출처와 확인 (2026-10-30)

2026년 10월 30일에 아래 문서를 다시 열어 대조했습니다. 모범 사례 문서가 개편돼 넣을 것·뺄 것 표, 강조 조언, /doctor 설명을 새 내용으로 고쳤습니다.

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