CLAUDE.md 설계 패턴집: 프로젝트 규모별로 활용하는 7가지 템플릿

핵심 요약
Claude Code의 출력 품질을 결정짓는 가장 중요한 요소는 프롬프트나 모델 성능이 아닌, CLAUDE.md 파일의 작성 방식이다.

1. 개요 및 CLAUDE.md의 역할

CLAUDE.md는 Claude Code가 코드를 생성하거나 수정할 때 자동으로 참조하는 프로젝트 지침서입니다. 프롬프트에 매번 반복 작성할 필요 없이, 프로젝트 전반의 **'암묵적 컨텍스트(Implicit Context)'**를 일관되게 유지시켜 줍니다.

주요 정의 사항

로딩 순서 및 스코프 계층 구조

CLAUDE.md는 3가지 스코프에 배치될 수 있으며, 하위 계층일수록 높은 우선순위를 가집니다.

graph TD
    A[Global Scope<br/>~/.claude/CLAUDE.md<br/>개인 설정 및 선호 스타일] --> B[Project Root Scope<br/>./CLAUDE.md<br/>공통 기술 스택 및 팀 규칙]
    B --> C[Subdirectory Scope<br/>./packages/api/CLAUDE.md<br/>특정 패키지/모듈 전용 제약]
스코프 경로 예시 주요 용도 공유 범위
User Global ~/.claude/CLAUDE.md 개인 설정 (선호 언어, 코딩 스타일) 개인 전용
Project Root ./CLAUDE.md 기술 스택, 전체 컨벤션 팀 전체 (Git 관리)
Subdirectory ./packages/api/CLAUDE.md 특정 패키지/모듈 전용 제약 팀 전체 (Git 관리)

Note: 서브디렉토리의 CLAUDE.md는 해당 디렉터리 내 파일을 작업할 때 추가 로드되며, 루트의 설정을 덮어쓰기보다는 보완하는 방식으로 설계하는 것이 권장됩니다.

2. 프로젝트 규모별 4가지 설계 패턴

패턴 1: 개인 스크립트용 (미니멀형)

# CLAUDE.md
## 프로젝트 개요
CLI 툴. 표준 입력으로 CSV를 받아 집계 결과를 JSON으로 출력함.

## 기술 스택
- Python 3.12
- 외부 라이브러리 사용 금지 (표준 라이브러리만 사용)

## 코딩 컨벤션
- 타입 힌트 필수
- 함수에는 1줄 Docstring 작성

## 빌드 및 실행
- 실행: `python main.py < input.csv`
- 테스트: `python -m pytest tests/`

패턴 2: 중규모 Web 앱용 (레이어 분리형)

# CLAUDE.md
## 프로젝트 개요
사내 재고 관리 시스템 (SaaS)

## 기술 스택
- Backend: TypeScript / NestJS / Prisma / PostgreSQL
- Frontend: TypeScript / Next.js (App Router) / Tailwind CSS v4
- Test: Vitest (Unit) / Playwright (E2E)
- CI: GitHub Actions

## 아키텍처 방침
### 디렉토리 구조 및 역할
- `src/domain/`: 도메인 모델 및 비즈니스 로직 (외부 의존성 금지)
- `src/application/`: 유즈케이스 (`domain`만 import 가능)
- `src/infrastructure/`: DB 및 외부 API 연동 (Prisma Client는 이 계층에서만 사용)
- `src/presentation/`: Controller, DTO, 유효성 검증

### 의존성 방향 (엄격 준수)
presentation → application → domain ← infrastructure

## 코딩 컨벤션
- 변수/함수: camelCase / 클래스: PascalCase
- `any` 사용 금지. `unknown` + 타입 가드 활용
- 에러는 Result 타입(neverthrow)으로 반환하며, `throw` 사용 자제
- 매직 넘버 금지 (`src/constants/`에 정의)

## 금지 사항 (Don'ts)
- `domain/`에서 `infrastructure/`를 직접 import 금지
- Prisma 모델 타입을 도메인 레이어로 노출 금지
- `console.log` 데버깅 금지 (Logger 활용)

## 테스트 방침
- domain / application: 단위 테스트 필수 (커버리지 80% 이상)
- infrastructure: 통합 테스트
- E2E: 주요 사용자 플로우 위주

## 주요 명령어
- 개발: `pnpm dev`
- 테스트: `pnpm test`
- 단일 테스트: `pnpm test -- --run src/path/to/file.test.ts`
- Lint: `pnpm lint`
- 마이그레이션: `pnpm prisma migrate dev`

패턴 3 & 4: 모노레포·팀 개발용 (계층형 CLAUDE.md + 서브디렉토리 분할)

graph TD
    Root[Root: ./CLAUDE.md<br/>전체 공통 규칙 & 패키지 간 의존성]
    Root --> API[packages/api/CLAUDE.md<br/>NestJS, OpenAPI, DB 모듈 규칙]
    Root --> Web[packages/web/CLAUDE.md<br/>Next.js, UI 컴포넌트, State 규칙]
    Root --> Shared[packages/shared/CLAUDE.md<br/>공통 유틸리티, Zero-dependency]

[패턴 3] 루트 CLAUDE.md (공통 규칙)

# CLAUDE.md (Root)
## 프로젝트 개요
커머스 플랫폼 모노레포 (pnpm workspace)

## 공통 규칙
- TypeScript strict 모드 필수
- 커밋 메시지: Conventional Commits 형식 준수
- PR 단위: 1기능 1PR (500줄 이하 권장)

## 패키지 간 의존성 규칙
- shared → 다른 패키지 의존 금지
- api, web → shared 참조 가능
- api ↔ web 간 직접 의존 엄금

## 공통 명령어
- 전체 빌드: `pnpm build`
- 전체 테스트: `pnpm test`
- 특정 패키지: `pnpm --filter @app/api test`

[패턴 4] 서브디렉토리 CLAUDE.md (packages/api/CLAUDE.md)

# CLAUDE.md (packages/api)
## 패키지 역할
REST API 서버 (인증, 재고, 주문 도메인 제공)

## 추가 기술 스택
- NestJS v10 / Prisma v6 / PostgreSQL 16

## 패키지 전용 규칙
- 엔드포인트 추가 시 OpenAPI 데코레이터 필수 작성
- `src/modules/` 하위에 기능 단위로 모듈 구성
- DB 마이그레이션 시 `pnpm prisma migrate dev --name <설명>` 사용

## 테스트
- `pnpm --filter @app/api test`

3. 용도 특화형 템플릿 (3가지 바리에이션)

프로젝트 규모와 별개로, 특정 작업 모드 실행 시 CLAUDE.md에 추가하거나 개인 글로벌 설정(~/.claude/CLAUDE.md)에 정의하여 사용하는 템플릿입니다.

패턴 5: 코드 리뷰 특화형

## 코드 리뷰 모드
다음 관점을 중점적으로 점검하여 리뷰를 진행하세요:

### 필수 체크 항목
1. **보안**: SQL 인젝션, XSS, 인증 우회 가능성
2. **성능**: N+1 쿼리, 불필요한 재렌더링, 메모리 누수
3. **에러 핸들링**: 예외 묵인, 민감 정보 유출 여부
4. **테스트**: 경계값 및 예외 케이스 누락 여부

### 리뷰 출력 형식
- 심각도 명시 (`Critical` / `Warning` / `Info`)
- 해당 코드 라인 번호 표시
- 수정 코드 예시 함께 제시

패턴 6: 테스트 생성 특화형

## 테스트 생성 모드
### 방침
- 프레임워크: Vitest
- AAA 패턴 (Arrange / Act / Assert) 구조화
- 원칙: 1 테스트 케이스당 1 Assertion

### 필수 테스트 케이스
- **정상계**: 대표적 입력에 대한 정상 동작
- **경계값**: 빈 배열, 빈 문자열, 0, 최대/최소값
- **이상계**: null/undefined, 타입 불일치, 네트워크 에러
- **멱등성**: 동일 입력에 대한 동일 결과 보장

### 모킹 규칙
- 외부 API 호출은 반드시 모킹
- DB는 In-memory SQLite 또는 Mock Repository 활용
- 시간 의존적 테스트는 `vi.useFakeTimers()` 활용

패턴 7: 리팩토링 특화형

## 리팩토링 모드
### 원칙
- 외부에서 보이는 동작(입출력)은 변경하지 않음
- 리팩토링 전 기존 테스트 통과 여부 확인
- 1 커밋당 1 리팩토링 수행

### 우선 적용 패턴
1. **함수 추출 (Extract Function)**: 5줄 이상 중첩 시 분리
2. **조기 리턴 (Guard Clause)**: 중첩 단계 축소
3. **매직 넘버 상수화**
4. **타입 엄격화**: `string` → Union 타입 / Branded 타입 변환

### 금지 사항
- 리팩토링에 신규 기능 추가 병행 금지
- 테스트가 없는 코드의 구조 변경 금지 (선 테스트 작성 후 진행)
- 성능 최적화와 리팩토링 동시 진행 금지

4. 안티패턴 및 적정 규모

CLAUDE.md는 길다고 좋은 것이 아닙니다. 아래 안티패턴을 주의해야 합니다.

안티패턴 유형 문제 증상 해결 방안
전부 넣기형 1개 파일에 모든 패키지 상세를 작성하여 300줄 초과 서브디렉토리 계층 분할 적용
추가 전용형 상충되는 지시문이 동거 (any 금지 vs 타입 무시 가능) 주기적(월 1회) 불필요 조항 삭제 및 리팩토링
코드 임베딩형 예시 코드를 50줄 이상 복사해 붙여넣음 예시는 5줄 이내로 최소화하고 문서 링크 참조
희망 사항형 "가독성 높은 코드를 작성하세요" 등 모호한 표현 "함수 30줄 이내", "중첩 3단계 이내" 등 구체적 규칙으로 변경
보안 정보 유입 API 키, DB 패스워드 등 작성 환경 변수명만 명시하고 .env 참조 유도

적정 작성 분량 가이드

5. 결론 및 프로젝트 첫날 15분 체크리스트

Claude Code 도입 효과를 극대화하려면 "해야 할 일"보다 "해서는 안 될 일(Don'ts)"을 명확히 규정하는 것이 핵심입니다.

🚀 프로젝트 첫날 15분 체크리스트