Claude Code용 CLAUDE.md 템플릿 7선 | 실제 프로젝트에 바로 붙여 넣는 예시

많은 CLAUDE.md 글은 “기술 스택을 적어라”에서 끝납니다. 틀린 말은 아니지만, Claude Code가 실제 업무를 건드리기 시작하면 그것만으로는 부족합니다.

정말 중요한 질문은 이것입니다. 이 저장소에서 같은 실수를 반복하지 않게 하려면 CLAUDE.md에 무엇을 써야 하는가?

이 글은 입문 가이드와 CLAUDE.md Best Practices 사이를 메우기 위해, 바로 복사해서 쓸 수 있는 템플릿 7개를 제공합니다.

가장 짧은 경로:

1. 무료 Claude Code Quick Reference Cheatsheet를 옆에 둡니다.
2. 내 저장소에 가장 가까운 템플릿 하나를 고릅니다.
3. 설명을 늘리기 전에 Do Not 규칙 3개를 먼저 추가합니다.
4. 더 많은 템플릿, hooks, permissions 예시가 필요하면 The Complete Claude Code Setup & Configuration Guide를 봅니다.
5. 팀 표준으로 정리하려면 consultation page로 갑니다.

좋은 CLAUDE.md가 실제로 하는 일

좋은 파일은 다음 세 가지 실패를 줄입니다.

• 맞는 파일을 건드렸지만 로컬 규칙을 어김
• 수정은 했지만 필요한 검증을 건너뜀
• 저장소 경계가 모호해서 너무 많은 파일을 탐색함

그래서 보통 다음 항목이 필요합니다.

• 기술 스택과 주요 명령
• 디렉터리 지도
• 프로젝트 고유 규칙
• 권장 작업 순서
• 금지 사항

특히 마지막 두 항목이 중요합니다. Claude Code는 어떻게 일할지와 무엇을 하지 말아야 하는지를 적어 주면 훨씬 안정적입니다.

템플릿 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

여기서 핵심은 스택 설명이 아니라 모바일 폭 검증과 공개 URL 확인을 성공 조건으로 적어 둔 점입니다.

템플릿 2: 수익 CTA가 있는 콘텐츠 사이트

# 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

무료 PDF, Gumroad, 상담 퍼널이 있는 사이트라면 일반 개발용 템플릿보다 이런 형태가 훨씬 실무적입니다.

템플릿 3: 백엔드 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

팀에서 자주 생기는 문제는 생산성이 낮은 것이 아니라, 패치가 리뷰하기 어렵다는 점입니다. 이 템플릿은 그 마찰을 줄입니다.

템플릿 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

레거시 작업에서는 compatibility over elegance가 가장 값비싼 문장일 때가 많습니다.

템플릿 6: 스크립트와 자동화 저장소

# 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

배포, 메일 발송, 외부 API 쓰기가 있다면 이 유형의 템플릿을 가장 먼저 고려하는 편이 안전합니다.

템플릿 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

모노레포에서 자주 망가지는 이유는 Claude Code가 패키지 경계를 너무 빨리 넘기기 때문입니다. ownership을 먼저 적어 두면 바로 좋아지는 경우가 많습니다.

피해야 할 실패 사례

실패 1: CLAUDE.md를 사내 위키처럼 길게 씀

긴 배경 설명은 토큰만 먹습니다. 짧고 실행 가능한 규칙이 더 낫습니다.

실패 2: 명령만 있고 워크플로가 없음

npm run test도 유용하지만, “billing 로직을 수정한 뒤에는 테스트를 돌려라”가 훨씬 강합니다.

실패 3: 금지 규칙이 없음

.env를 건드리지 말 것, 공개 URL 확인 없이 배포 성공이라고 하지 말 것, force push 금지 같은 문장이 실제 사고를 막습니다.

실패 4: 파일을 갱신하지 않음

Claude Code가 같은 실수를 세 번 반복한다면, 보통 모델보다 CLAUDE.md가 덜 구체적인 쪽이 문제입니다.

어떤 템플릿을 골라야 하나

• UI나 제품 작업 중심이면 개인 앱 템플릿
• 다국어 글, 무료 PDF, Gumroad 퍼널이 중요하면 콘텐츠 사이트 템플릿
• 검증과 데이터 정합성이 중요하면 API 템플릿
• 진짜 병목이 협업이면 팀 또는 모노레포 템플릿
• 실수 비용이 크면 레거시 또는 자동화 템플릿

7개를 전부 합칠 필요는 없습니다. 하나를 기반으로 하고, 실제로 행동을 바꾸는 규칙만 추가하면 됩니다.

다음 단계

1. 템플릿 하나를 CLAUDE.md에 복사합니다.
2. 프로젝트 전용 Do Not 규칙 3개를 추가합니다.
3. 이 저장소에서 “완료”가 무엇인지 한 줄로 적습니다.

빠른 일일 참고용이라면 무료 Claude Code Quick Reference Cheatsheet부터 보세요. 더 많은 CLAUDE.md 예시, 설정, hooks, permissions, workflow 패턴이 필요하면 The Complete Claude Code Setup & Configuration Guide를 추천합니다. 팀 운영 모델까지 정리하고 싶다면 consultation page가 가장 빠릅니다.