CLAUDE.md에 뭘 써야 할까? 바로 붙여 쓰는 템플릿 7개와 금지 규칙 만드는 법

“CLAUDE.md, 일단 기술 스택만 적어두면 되는 거 아냐?”

저도 처음엔 그렇게 생각했습니다. Astro랑 TypeScript랑 Tailwind, 네 다 적었어요. 그러고 만족한 채로 Claude Code에 작업을 맡겼더니——같은 실수를 세 번이나 반복하더군요. 매번 테스트를 건너뛰고, 건드리면 안 되는 설정 파일에 손을 뻗고, “고쳤습니다!”라고 말하면서 정작 빌드는 통과하지 않은 채로요.

스택만 적은 CLAUDE.md는, 신입에게 “우리는 자바 쓰는 회사야”라고만 말하고 현장에 던져 넣는 것과 똑같습니다. 무엇을 아는지는 전달되지만, 어떻게 움직여야 하는지는 하나도 전달되지 않은 거죠.

이 글에서는 제가 실제 프로젝트에서 그대로 쓰고 있는 CLAUDE.md 템플릿 7개를, 복붙할 수 있는 형태로 올려둡니다. 스택 설명이 아니라 “일하는 순서”와 “해서는 안 되는 것”에 완전히 집중한 버전입니다.

핵심 요약

• CLAUDE.md에서 진짜 효과가 있는 건 기술 스택이 아니라, 작업 순서(Working Rules)와 금지 사항(Do Not) 두 가지입니다.
• 용도별로 템플릿 7개를 준비했습니다. 개인 개발 / 콘텐츠 사이트 / API / 팀 / 레거시 / 자동화 / 모노레포. 내 저장소에 가장 가까운 하나를 골라 붙이기만 하면 됩니다.
• 어느 템플릿이든, 붙인 뒤에 내 상황에 맞는 Do Not을 3줄 더하는 게 필수입니다. 이게 사고를 막아 줍니다.
• 길게 쓸수록 좋다는 건 오해입니다. CLAUDE.md는 매뉴얼이 아니라 운영 파일입니다. 짧은 행동 규칙이 이깁니다.
• Claude Code가 같은 실수를 세 번 반복하면, AI가 아니라 CLAUDE.md의 입자 크기(구체성)를 의심하세요.

이 페이지는 Claude Code 입문 가이드와 CLAUDE.md 작성법 완전 가이드 사이를 메우는 “실물 카탈로그”로 만들었습니다. 이론은 그쪽에서 읽으시고, 여기서는 실물을 챙겨 가세요.

좋은 CLAUDE.md가 조용히 해내고 있는 일

강한 CLAUDE.md는 똑똑한 내용을 적어 둔 게 아닙니다. 다음 세 가지 “흔한 사고”를 조용히 막아 줄 뿐입니다.

• 편집할 위치는 맞는데, 그 프로젝트 고유의 관례를 놓침
• 수정 자체는 됐는데, 돌려야 할 테스트나 확인을 건너뜀
• 내 담당 범위가 어디까지인지 모호해서, 탐색이 너무 넓어져 시간을 녹임

이 세 가지를 막기 위해, 최소한 있어야 할 항목은 이렇습니다.

항목	역할	효과
기술 스택과 주요 명령	전제를 맞춘다	중
디렉터리의 역할	탐색 범위를 좁힌다	중
프로젝트 고유 규칙	관례를 지키게 한다	대
작업 순서(순서)	확인 누락을 막는다	대
금지 사항(Do Not)	사고를 멈춘다	특대

위 두 개는 덤이고, 진짜 효과가 있는 건 아래 세 개입니다. 특히 작업 순서와 금지 사항을 적는 순간, Claude Code는 딴사람처럼 차분해집니다. “어떻게 진행할지”와 “무엇을 하지 말지”——결국 사람 신입에게 건네는 매뉴얼과 똑같은 거죠.

여기서부터는 실물입니다. 코드 블록 안의 내용을 자신의 CLAUDE.md에 그대로 붙여 넣으세요.

1. 개인 개발 웹 앱용

혼자서 작은 서비스를 돌리고 있다면, 우선 이것부터입니다.

# Project Overview

Customer-facing Astro site with a small Node API.

## Tech Stack

- Frontend: Astro 5 + TypeScript
- Styling: Tailwind CSS
- Backend: Node.js 22
- Tests: Vitest

## Key Directories

- `site/src/pages/` route entrypoints
- `site/src/components/` reusable UI
- `site/src/content/` blog and docs content
- `scripts/` operational scripts

## Common Commands

- Build: `cd site && npm run build`
- Test: `npm run test`
- Search content: `rg "keyword" site/src/content`

## Working Rules

- Prefer minimal diffs over wide refactors
- Keep copy changes aligned with existing brand tone
- When editing UI, verify mobile width before calling the task done

## Do Not

- Do not rename routes unless required
- Do not delete analytics or SEO fields
- Do not claim deploy success without checking the public URL

여기서 가장 효과가 큰 건 스택 설명이 아니라 Working Rules와 Do Not의 마지막 줄입니다. “모바일 폭을 확인할 때까지 완료라고 말하지 마라”, “공개 URL을 볼 때까지 배포 성공이라고 말하지 마라”. 이 두 줄을 넣기 전, 저는 PC 화면에서는 멀쩡하던 UI가 스마트폰으로 보니 전부 삐져나오는 사고를 몇 번 쳤습니다. 성공 조건을 문장으로 묶어 두면 그게 사라집니다.

2. 글·PDF·상품 동선이 있는 콘텐츠 사이트용

이 블로그 자체가 그렇지만, 수익 동선이 있는 사이트는 일반적인 개발 템플릿으로는 너무 약합니다.

# Project Overview

Multilingual Claude Code content site with free PDF lead magnet, Gumroad products, and consultation funnel.

## Business Goal

- Priority 1: free PDF registration
- Priority 2: Gumroad product clicks and purchases
- Priority 3: consultation inquiries

## Content Rules

- Every new article must include internal links
- Every article must include free PDF, product, and consultation CTA paths
- Use the same slug across all locales when publishing multilingual posts

## Verification Workflow

1. Build the site
2. Deploy the site
3. Open the public URL
4. Check mobile layout
5. Confirm CTA destination links

## Do Not

- Do not publish only one locale when the article requires all locales
- Do not treat build success as release success
- Do not prioritize pageviews over conversion path quality

포인트는 Do Not의 마지막 줄, “PV보다 전환 동선의 품질을 우선하라”고 명시한 점입니다. 이걸 안 적으면 Claude Code는 “읽힐 것 같은 글”을 만드는 쪽으로 기울어, 정작 CTA가 빈약한 페이지를 양산합니다. 비즈니스 목표에 우선순위를 매겨 맨 앞에 두기만 해도, 출력의 방향이 확 달라졌습니다.

3. 백엔드 API용

정합성이 생명인 API에는 “고치기 전에 읽기”, “고쳤으면 말로 설명하기”를 강제합니다.

# Project Overview

Internal TypeScript API for billing and account management.

## Tech Stack

- Node.js 22
- Fastify
- PostgreSQL + Prisma
- Zod
- Vitest

## Directory Map

- `src/routes/` HTTP handlers
- `src/services/` business logic
- `src/repositories/` DB access
- `src/lib/` shared utilities

## Required Workflow

1. Read the route or service first
2. Check for existing schema and tests
3. Make the smallest safe change
4. Run unit tests or type checks
5. Summarize risk in plain English

## Do Not

- Do not bypass Zod validation
- Do not edit migrations casually
- Do not touch billing logic without tests

이 중에서 제가 가장 아끼는 건 Summarize risk in plain English 한 줄입니다. 직역하면 “리스크를 평범한 말로 정리하라”. 이걸 넣으면 Claude Code가 “고쳤습니다”로 끝내지 않고, “이 변경은 과금 로직 경계에 가까워서 월간 배치에 영향을 줄 수 있습니다”처럼 영향 범위를 알아서 말로 풀어 줍니다. 리뷰의 첫 수가 단번에 편해집니다.

4. 팀 개발용

팀에서 정말 곤란한 건 생산성 부족보다 리뷰하기 어려운 변경분입니다. 그걸 미리 차단합니다.

# Team Workflow

- Work on the current branch only
- Do not revert changes you did not make
- Call out uncertainty before making broad edits
- Prefer review-friendly patches over large rewrites

## Pull Request Expectations

- Mention user-facing behavior changes
- Mention test coverage gaps
- Flag security, permissions, and deploy risks first

## Approval Boundaries

- Ask before deploy commands
- Ask before editing CI, infra, or secrets-related files
- Ask before changing lockfiles unless required

Do not revert changes you did not make(내가 하지 않은 변경을 멋대로 되돌리지 마라)는 수수해 보이지만 효과가 있습니다. AI는 “겸사겸사” 근처 코드를 ‘깔끔하게’ 만들려다, 다른 사람의 의도적인 코드를 되돌려 버리는 일이 있거든요. 승인 경계를 나누는 방법은 Approval / Sandbox 설정 가이드에서 자세히 다뤘으니, 팀 운영이라면 그쪽도 함께 보세요.

5. 레거시 코드용

오래된 코드를 손볼 때는 “깔끔함”보다 “망가뜨리지 않는 것”이 정의가 됩니다.

# Legacy Repo Notes

- This codebase has inconsistent patterns
- Prefer compatibility over elegance
- Preserve behavior unless the task explicitly allows change

## Investigation First

1. Explain current behavior
2. Locate the smallest responsible file set
3. Identify risks before editing

## Do Not

- Do not rename public methods casually
- Do not introduce new frameworks
- Do not rewrite files only to match modern style

Prefer compatibility over elegance(아름다움보다 호환성을 우선). 레거시 프로젝트에서는 이게 가장 중요해지는 경우가 많습니다. 내버려 두면 Claude Code는 선의로 “최신 스타일로 다시 작성할게요”라고 말하는데, 레거시에서는 그게 사고의 입구입니다. Do not rewrite files only to match modern style을 금지에 넣어 그 선의에 뚜껑을 덮어 둡니다.

6. 자동화·운영 스크립트용

메일 발송, 배포, 외부 API 쓰기——부작용이 있는 스크립트를 만지게 한다면, 첫 후보는 이것입니다.

# Automation Rules

- Dry-run whenever the script supports it
- Log intended side effects before executing
- Prefer idempotent operations
- Keep secrets out of logs and generated files

## Required Checks

- Confirm environment variables used
- Confirm target environment
- Confirm output path or destination service

## Do Not

- Do not send emails, deploy, or publish without explicit approval
- Do not delete generated assets unless cleanup is requested

Log intended side effects before executing(실행하기 전에, 무슨 짓을 저지를 셈인지 적어 내라)가 안전판입니다. “이제부터 운영 환경에 메일 120통을 보냅니다”라고 먼저 선언하게 하면, 사람이 “잠깐”을 외칠 수 있습니다. Dry-run whenever the script supports it과 한 세트로 두면, 돌이킬 수 없는 작업에 반드시 한 박자가 끼어듭니다.

7. 모노레포용

여러 앱과 공유 패키지가 한곳에 있다면, “어느 패키지가 책임을 지는지”를 먼저 적습니다.

# Monorepo Map

- `apps/web/` customer app
- `apps/admin/` internal admin tool
- `packages/ui/` shared UI
- `packages/config/` lint and tsconfig presets

## Ownership Rules

- Web UI work should stay inside `apps/web/` unless the task clearly needs a shared component change
- Shared package edits require checking downstream usage
- Avoid version or config churn unless necessary

## Verification

- Run the narrowest relevant build or test command first
- Describe cross-package impact before editing shared code

Ownership Rules를 적어 두기만 해도 횡단 편집 사고가 꽤 줄어듭니다. apps/web/의 작은 수정일 줄 알았는데, 어느새 packages/ui/의 공유 컴포넌트에 손이 들어가 apps/admin/까지 휘말려 망가진다——이게 모노레포의 전형적인 사고죠. 담당 범위를 처음에 선언하게 하고, 공유 코드에 손대기 전에 “하류로의 영향을 설명하라”고 한마디 넣어 둡니다.

어떤 템플릿을 골라야 할까

7개나 늘어놓으면 헷갈리니, 고르는 법을 한 줄씩 정리해 둡니다.

• UI나 제품이 중심 → 개인 개발 템플릿
• 글·PDF·Gumroad 동선이 있다 → 콘텐츠 사이트 템플릿
• 정합성이 생명 → API 템플릿
• 조율 비용이 크다 → 팀 또는 모노레포 템플릿
• 사고 비용이 크다 → 레거시 또는 자동화 템플릿

7개를 전부 섞을 필요는 없습니다. 오히려 섞으면 길어져서 효과가 떨어집니다. 하나를 토대로 삼고, 내 현장에서 행동이 바뀌는 규칙만 더한다. 이게 정답입니다.

CLAUDE.md에서 저지르기 쉬운 실패 4가지

제가 실제로 밟은 지뢰를 그대로 공유합니다.

실패 1. 회사 위키처럼 길게 쓴다. 설명이 길수록 좋다는 건 완전한 오해였습니다. CLAUDE.md는 매뉴얼이 아니라 운영 파일입니다. 긴 배경 설명보다 짧은 행동 규칙이 몇 배는 효과적입니다. 읽는 건 사람이 아니라 AI라는 전제를 자꾸 잊게 되더라고요.

실패 2. 명령만 적고, 순서를 적지 않는다. npm run test라고만 적기보다, billing을 만지면 test를 반드시 돌려라가 압도적으로 강합니다. 명령은 “존재”만 알려 줍니다. 순서는 “언제 쓸지”까지 알려 줍니다.

실패 3. 금지 사항이 없다. 이게 제일 아깝습니다. .env를 만지지 마라, 공개 URL을 확인하지 않고 배포 성공이라고 말하지 마라, force push 하지 마라. 단 한 문장이 하룻밤의 사고를 막습니다. Do Not 섹션은 장식이 아니라 보험입니다.

실패 4. 갱신하지 않는다. Claude Code가 같은 실수를 세 번 반복하면, 대개 AI 탓이 아니라 CLAUDE.md 쪽의 입자 크기(구체성)가 부족한 겁니다. 그럴 때는 혼내지 말고 규칙을 한 줄 덧붙이세요. CLAUDE.md는 쓰고 끝나는 게 아니라, 키워 가는 파일입니다.

자주 묻는 질문

Q. CLAUDE.md는 프로젝트 어디에 두어야 하나요? A. 저장소 루트에 CLAUDE.md라는 이름으로 두면 Claude Code가 자동으로 읽어 들입니다. 모노레포라면 각 패키지 바로 아래에도 둘 수 있고, 가까운 쪽이 우선됩니다. 실제로 두는 법과, 잘 먹히는지 확인하는 건 이 두 명령뿐입니다.

# 프로젝트 루트에 두기만 하면 됨. Claude Code가 시작할 때 자동으로 읽어 들인다
cat > CLAUDE.md <<'EOF'
# Project
(위 템플릿을 그대로 붙여 넣는다)
EOF

# 잘 먹히는지 확인: 규칙을 되물어 본다
claude -p "이 프로젝트의 CLAUDE.md에 있는 Do Not을 3개 들어 줘"

자세한 배치 규칙은 공식 Claude Code documentation을 확인하세요.

Q. 한국어로 써도 제대로 먹히나요? A. 먹힙니다. 저는 금지 사항이나 순서를 일본어로 쓸 때도 있습니다. 다만 템플릿 자체는 영어로 써 두면 해외 멤버나 샘플과도 맞추기 쉬워서, 이 글에서는 영어를 기본으로 했습니다. 내용만 전달되면 어느 쪽이든 문제없습니다.

Q. 긴 CLAUDE.md와 짧은 CLAUDE.md, 어느 쪽이 좋나요? A. 짧은 쪽입니다. 기준은 한 화면에 들어올 정도. 길어지기 시작하면, 그건 별도 문서로 떼어 내라는 신호입니다. CLAUDE.md에는 “행동이 바뀌는 규칙”만 남기세요.

Q. 템플릿을 붙인 다음, 가장 먼저 무엇을 더해야 하나요? A. 내 프로젝트용 Do Not 3줄입니다. “건드리면 곤란한 파일”, “당하면 곤란한 작업”, “들으면 곤란한 거짓말(예: 확인도 안 하고 성공 보고)“을 각각 한 줄씩. 여기가 가장 수익이 큰 추가입니다.

Q. CLAUDE.md와 permissions(권한 설정)는 어떻게 다른가요? A. CLAUDE.md는 “부탁·방침”, permissions는 “강제력이 있는 허용 목록”입니다. 금지 사항을 진심으로 지키게 하고 싶다면 둘을 함께 씁니다. 권한 나누는 법은 Claude Code 입문 가이드에서도 다룹니다.

실제로 시험해 본 결과

CLAUDE.md에 기술 스택만 적어 두던 시절, 저는 Claude Code의 출력에 매번 조마조마했습니다. “이번엔 테스트를 제대로 돌려 주려나” 하고요.

Working Rules와 Do Not을 더한 뒤로 그 불안이 거의 사라졌습니다. 특히 “공개 URL을 볼 때까지 배포 성공이라고 말하지 마라” 한 줄은 효과가 뚜렷하게 숫자로 나옵니다. 그 전에는 “배포했습니다” 뒤에 실제로는 404, 같은 일이 한 달에 몇 번씩 있었는데, 넣고 나서는 0이 됐습니다.

결론은 단순합니다. CLAUDE.md는 AI를 똑똑하게 만드는 파일이 아니라, AI가 사고 치지 않게 하는 파일입니다. 스택을 더하는 것보다 금지 사항을 3줄 더하는 게, 체감상 10배는 효과가 큽니다. 우선 내 저장소에 가장 가까운 템플릿 하나를 붙이고, Do Not을 3줄만 적어 보세요.

CLAUDE.md의 설계 사상 자체를 더 깊이 파고들고 싶은 분은 CLAUDE.md 작성법 완전 가이드를, AI에 작업을 안전하게 맡기는 “발판” 전체 이야기는 “전부 알아서 해 둬”는 사고의 시작을 보세요. 템플릿 모음과 설정 예시를 손안에 정리해 두고 싶다면, 무료 Claude Code Quick Reference Cheatsheet와 hooks·permissions까지 파고든 The Complete Claude Code Setup & Configuration Guide가 도움이 됩니다. 교재를 한 번 둘러보고 싶은 분은 교재 목록에서, 팀 표준화까지 함께 다듬고 싶은 분은 도입 상담으로 오세요.