CLAUDE.md 실전 예제 모음: 웹앱·모노레포·규칙·안티패턴 복붙 템플릿

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 프로젝트 지침 파일입니다. 개념과 설정은 별도 가이드에서 다루므로, 이 글은 바로 복사해 쓸 수 있는 상황별 예제와 흔한 안티패턴을 모았습니다. 모든 예제는 Anthropic 공식 메모리 문서의 형식을 따릅니다. (기준 시점: 2026년 6월, 회사명·스택은 예시)

무엇을 담아야 하나

공식 권고는 "매번 다시 설명하게 되는 것"을 적는 것입니다. 다음 상황에서 항목을 추가하세요: Claude가 같은 실수를 두 번째로 했을 때, 코드 리뷰가 Claude가 알았어야 할 것을 지적했을 때, 지난 세션에 입력한 교정을 또 입력하게 될 때, 새 팀원에게 똑같이 설명해야 할 맥락일 때. 빌드 명령·컨벤션·구조·"항상 X" 규칙처럼 모든 세션에 필요한 사실만 담고, 여러 단계 절차나 일부 영역에만 해당하는 내용은 스킬이나 경로 스코프 규칙으로 옮기는 것이 좋습니다.

예제 1 — 웹앱 프로젝트(./CLAUDE.md)

팀이 버전 관리로 공유하는 가장 일반적인 형태입니다. 명령·컨벤션·주의사항을 구체적으로 적습니다.

# 프로젝트: 사내 대시보드 (예시)

## 기술 스택
- Next.js(App Router) + TypeScript + Tailwind

## 명령
- 개발: `pnpm dev`
- 빌드: `pnpm build`
- 테스트: `pnpm test` (커밋 전 반드시 실행)
- 린트: `pnpm lint`

## 컨벤션
- 들여쓰기 2칸, 세미콜론 사용
- 컴포넌트는 `src/components/`, API 핸들러는 `src/app/api/`
- 커밋 전 `pnpm lint` 통과 필수

## 주의
- `src/lib/db/` 스키마 파일은 마이그레이션 없이 수정 금지

예제 2 — 모노레포 루트

모노레포에서는 루트에 공통 규칙만 두고, 각 패키지가 자체 CLAUDE.md를 갖게 합니다. @import로 README나 릴리스 문서를 끌어올 수 있습니다(상대·절대 경로 모두 가능, 최대 4단계).

# 모노레포 루트 (예시)

각 패키지는 자체 CLAUDE.md를 가집니다. 공통 규칙만 여기에 둡니다.

## 공통 규칙
- 패키지 매니저: pnpm (npm/yarn 금지)
- 모든 패키지는 `pnpm -F <pkg> test` 로 테스트

## 임포트
See @README for overview.
- 릴리스 절차 @docs/release.md

예제 3 — 경로 스코프 규칙(.claude/rules/)

큰 프로젝트는 지침을 .claude/rules/의 주제별 파일로 나눌 수 있습니다. YAML paths 프런트매터를 쓰면 해당 패턴의 파일을 다룰 때만 규칙이 로드되어 컨텍스트를 아낍니다.

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

# API 개발 규칙
- 모든 엔드포인트는 입력 검증 포함
- 표준 에러 응답 형식 사용
- OpenAPI 주석 작성

예제 4 — AGENTS.md를 쓰던 프로젝트

Claude Code는 AGENTS.md가 아니라 CLAUDE.md를 읽습니다. 이미 AGENTS.md를 쓴다면, 그것을 임포트하는 CLAUDE.md를 만들어 중복 없이 두 도구가 같은 지침을 읽게 합니다.

@AGENTS.md

## Claude Code
- `src/billing/` 아래 변경은 plan 모드 사용

흔한 안티패턴

• 막연한 지시: "코드를 깔끔하게"보다 "2칸 들여쓰기 사용"처럼 검증 가능하게 씁니다.
• 거대한 파일: 파일당 200줄 이하를 목표로 합니다. 길수록 컨텍스트를 더 쓰고 준수율이 떨어집니다. @import로 나눠도 임포트 파일은 시작 시 함께 로드되어 컨텍스트가 줄지 않으므로, 줄이려면 경로 스코프 규칙을 쓰세요.
• 충돌하는 규칙: 두 규칙이 모순되면 Claude가 임의로 하나를 고를 수 있습니다. 정기적으로 검토해 충돌을 제거합니다.
• 절차·일회성까지 넣기: 여러 단계 절차는 스킬로, 특정 영역만의 규칙은 경로 스코프 규칙으로 옮깁니다.

다듬는 순서

/init으로 초안을 자동 생성한 뒤(이미 파일이 있으면 개선안을 제안), 실사용하며 반복되는 교정을 규칙으로 추가합니다. /memory로 현재 세션에 어떤 CLAUDE.md·규칙 파일이 로드됐는지 확인하고 정리할 수 있습니다. CLAUDE.md는 시스템 프롬프트가 아니라 컨텍스트로 전달되므로 엄격한 강제는 아닙니다 — 커밋 전처럼 특정 시점에 반드시 실행돼야 하는 것은 훅(hook)으로 작성하는 것이 안전합니다.

함께 보면 좋은 글

원리·설정 전반은 CLAUDE.md 완벽 가이드에서 다룹니다. 반복 작업을 패키지로 묶는 방법은 Claude Code 스킬 가이드를 참고하세요.

처음이라면: 처음 만드는 CLAUDE.md (입문)