[Claude] CLAUDE.md 작성법 - 프로젝트별 최적화 컨텍스트 만들기

"이 프로젝트는 TypeScript를 사용해"라고 매번 반복하시나요?

CLAUDE.md 파일 하나면 Claude가 프로젝트를 완벽히 이해합니다.

이번 가이드에서는 프로젝트 전용 AI 어시스턴트를 만드는 CLAUDE.md 작성법을 A부터 Z까지 소개합니다.

 

CLAUDE.md란?

CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽는 마크다운 파일로, 프로젝트별 지침과 컨텍스트를 제공합니다.

 

왜 필요한가?

CLAUDE.md 없이:

나: "이 프로젝트는 Next.js 14를 사용해. TypeScript strict 모드야.
     Tailwind CSS로 스타일링하고, Jest로 테스트해.
     컴포넌트는 /src/components에 있어..."

↓ (다음 세션에서 똑같이 반복)

CLAUDE.md 사용 시:

나: "로그인 기능을 추가해줘."

Claude: (자동으로 Next.js 14, TypeScript, Tailwind 패턴 적용)

 

핵심 가치

효과	설명
컨텍스트 절약	반복 설명 불필요 (세션당 수천 토큰 절약)
일관성	프로젝트 스타일 자동 준수
생산성	즉시 정확한 코드 생성
지식 보존	팀 전체의 컨벤션 문서화
신규 팀원	온보딩 가속화

 

작동 원리

1. Claude Code 세션 시작
        ↓
2. CLAUDE.md 자동 로드
        ↓
3. 시스템 프롬프트에 컨텍스트 추가
        ↓
4. 프로젝트 패턴 자동 적용
        ↓
5. 일관된 코드 생성

 

파일 위치 및 구조

표준 위치

프로젝트 루트 (권장):

your-project/
├── CLAUDE.md          ← 여기!
├── src/
├── tests/
└── package.json

또는 .claude 디렉토리:

your-project/
├── .claude/
│   └── CLAUDE.md      ← 여기도 가능
├── src/
└── package.json

우선순위:

1. ./CLAUDE.md (프로젝트 루트)
2. ./.claude/CLAUDE.md
3. ~/.claude/CLAUDE.md (글로벌 설정)

모듈화된 구조 (.claude/rules/)

대규모 프로젝트용:

your-project/
├── .claude/
│   ├── CLAUDE.md              # 메인 지침
│   └── rules/                 # 모듈별 규칙
│       ├── code-style.md
│       ├── testing.md
│       ├── security.md
│       └── frontend/
│           ├── components.md
│           └── state-management.md
├── src/
└── tests/

장점:

• 한 파일에 모든 것을 넣지 않음
• 팀원별로 책임 영역 분리
• 재사용 가능한 규칙 공유 (심볼릭 링크)

자동 로드:
.claude/rules/ 디렉토리의 모든 .md 파일이 자동으로 로드됩니다!

 

필수 섹션

1. 프로젝트 개요

# 프로젝트 컨텍스트

이 프로젝트는 Next.js 14 기반의 전자상거래 플랫폼입니다.
Stripe 결제 통합, 실시간 재고 관리, 관리자 대시보드를 포함합니다.
팀 규모: 4명의 개발자.

포인트:

• 1-2문장으로 프로젝트 정의
• 핵심 기능 나열
• 팀 규모 및 배경 (선택)

 

2. 기술 스택

## 기술 스택

### Frontend
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS + shadcn/ui
- State: Zustand
- Testing: Jest + React Testing Library

### Backend
- Runtime: Node.js 20
- API: Next.js API Routes + tRPC
- Database: PostgreSQL + Prisma ORM
- Auth: NextAuth.js

### DevOps
- Package Manager: pnpm
- CI/CD: GitHub Actions
- Hosting: Vercel

 

3. 코드 스타일

## 코드 컨벤션

### TypeScript
- `strict: true` 모드 사용
- 명시적 반환 타입 선호
- `any` 사용 금지

### 네이밍
- 컴포넌트: PascalCase (예: `ProductCard.tsx`)
- 함수: camelCase (예: `getUserData`)
- 상수: UPPER_SNAKE_CASE (예: `API_URL`)
- 파일: kebab-case (예: `user-profile.tsx`)

### 파일 구조
- 한 파일당 하나의 주요 export
- Named exports 선호 (default export 지양)
- 관련 타입은 같은 파일에 정의

### 스타일링
- Tailwind 유틸리티 클래스 사용
- 복잡한 스타일은 `class-variance-authority` 활용
- 인라인 스타일 지양

### Import 순서
1. React 및 외부 라이브러리
2. 내부 컴포넌트
3. 유틸리티 및 헬퍼
4. 타입 정의
5. 스타일

 

4. 아키텍처

## 프로젝트 구조

/src
├── app/               # Next.js App Router (페이지 & 레이아웃)
├── components/        # 재사용 가능한 UI 컴포넌트
├── features/          # 기능별 모듈 (Vertical Slice)
│   ├── auth/
│   ├── products/
│   └── checkout/
├── lib/               # 유틸리티 및 헬퍼
├── hooks/             # 커스텀 React Hooks
├── types/             # TypeScript 타입 정의
└── server/            # tRPC 라우터 및 서버 로직

## 아키텍처 패턴

### Vertical Slice Architecture
- 기능별로 폴더 구성 (features/)
- 각 기능은 독립적인 모듈
- 컴포넌트, 훅, API 로직을 함께 관리

### Server vs Client Components
- 기본: Server Component
- 인터랙션 필요 시만 `'use client'` 사용
- 클라이언트 번들 사이즈 최소화

### 상태 관리
- 로컬 상태: useState
- 전역 상태: Zustand
- 서버 상태: React Query (tRPC)
- URL 상태: Next.js 라우터 (searchParams)

 

5. 테스팅 가이드라인

## 테스팅 요구사항

### 커버리지 목표
- 최소: 80% (src/ 디렉토리)
- 목표: 90%

### 테스트 종류
1. **Unit Tests**: 유틸리티 함수 및 Hooks
2. **Integration Tests**: API 엔드포인트
3. **Component Tests**: React 컴포넌트
4. **E2E Tests**: 핵심 사용자 플로우

### 테스트 작성 규칙
- 각 기능에 긍정/부정/경계값 테스트 모두 포함
- `data-testid` 사용 (텍스트 기반 쿼리 지양)
- 모킹: 외부 API는 항상 모킹
- 파일 위치: `__tests__/` 디렉토리 또는 `.test.tsx` 확장자

### 테스트 명령어
```bash
npm test              # 모든 테스트 실행
npm test:watch        # Watch 모드
npm test:coverage     # 커버리지 리포트
npm run test:e2e      # E2E 테스트

### 6. 보안 가이드라인

```markdown
## 보안 요구사항

### 인증 및 권한
- 모든 API 엔드포인트에 인증 확인
- JWT 토큰 유효성 검사 필수
- RBAC (역할 기반 접근 제어) 적용

### 데이터 보호
- `.env` 파일 절대 커밋 금지
- API 키는 환경 변수로만 관리
- 민감 데이터 로그 출력 금지
- 사용자 입력 항상 검증 (Zod 스키마 사용)

### OWASP Top 10 준수
- SQL Injection: Prisma ORM 사용 (Raw SQL 금지)
- XSS: DOMPurify로 사용자 입력 sanitize
- CSRF: NextAuth.js 자동 처리
- Rate Limiting: API 미들웨어에 구현됨

### 취약점 스캔
- `npm audit` 주기적 실행
- 의존성 자동 업데이트 (Dependabot)

 

7. 명령어 및 워크플로우

## 주요 명령어

### 개발
```bash
npm run dev           # 개발 서버 시작 (localhost:3000)
npm run build         # 프로덕션 빌드
npm run start         # 프로덕션 서버 실행

 

데이터베이스

npm run db:migrate    # Prisma 마이그레이션 실행
npm run db:seed       # 시드 데이터 추가
npm run db:studio     # Prisma Studio 실행

 

테스팅

npm test              # 모든 테스트
npm run lint          # ESLint 실행
npm run type-check    # TypeScript 타입 체크

 

배포

npm run deploy:staging    # 스테이징 배포
npm run deploy:prod       # 프로덕션 배포

 

일반적인 워크플로우

새 기능 추가

1. 기능 브랜치 생성: git checkout -b feature/기능명
2. 코드 작성 + 테스트 작성
3. 테스트 실행: npm test
4. 린트 체크: npm run lint
5. PR 생성

버그 수정

1. 재현 테스트 작성
2. 버그 수정
3. 모든 테스트 통과 확인
4. PR 생성

 

실전 예시

예시 1: Next.js + TypeScript 프로젝트

# TechStore - E-commerce Platform

## 프로젝트 컨텍스트
Next.js 14 전자상거래 플랫폼. Stripe 결제, 실시간 재고, 관리자 대시보드 포함.

## 기술 스택
- Frontend: Next.js 14, React 18, TypeScript, Tailwind CSS
- Backend: tRPC, Prisma, PostgreSQL
- Auth: NextAuth.js
- Payment: Stripe
- Testing: Vitest, React Testing Library

## 코드 스타일
- TypeScript `strict: true`
- Named exports 선호
- PascalCase: 컴포넌트, camelCase: 함수
- Tailwind 유틸리티 + CVA for variants

## 명령어
```bash
npm run dev          # :3000
npm test             # Vitest
npm run db:migrate   # Prisma migrations

디렉토리 구조

/src
├── app/           # Pages & Layouts
├── components/    # Reusable UI
├── features/      # Feature modules
├── lib/           # Utilities
├── hooks/         # Custom hooks
└── server/        # tRPC routers

 

핵심 패턴

1. API 호출

// ✅ Good: tRPC로 타입 안전
const { data } = trpc.products.getAll.useQuery();

// ❌ Bad: fetch로 직접 호출
const response = await fetch('/api/products');

2. 상태 관리

// ✅ Good: 서버 상태는 React Query
const { data } = useQuery(['products'], fetchProducts);

// ✅ Good: 클라이언트 상태는 Zustand
const cart = useCartStore(state => state.items);

3. 에러 처리

// ✅ Good: { error } 객체 반환
return { error: 'User not found' };

// ❌ Bad: throw 사용 (API 라우트에서)
throw new Error('User not found');

4. 입력 검증

// ✅ Good: Zod 스키마 사용
const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
});

보안

• 환경 변수: .env.local (dev), Vercel Secrets (prod)
• CSRF: NextAuth 자동 처리
• Rate limit: API 미들웨어 구현됨
• 입력 검증: 항상 Zod

주의사항

• API 라우트는 /src/app/api/에만 위치
• 클라이언트 컴포넌트는 필요 시에만 사용
• DB 마이그레이션은 배포 전 필수 커밋
• Stripe 웹훅은 raw body 사용 (JSON 파싱 금지)

 

예시 2: Python FastAPI 프로젝트

# NotificationService - Microservice API

## 개요
FastAPI 기반 실시간 알림 마이크로서비스.
이메일, SMS, 푸시 알림을 처리합니다.

## 기술 스택
- Framework: FastAPI 0.104+
- Server: Uvicorn + Gunicorn
- DB: PostgreSQL + SQLAlchemy (async)
- Queue: RabbitMQ
- Cache: Redis
- Testing: pytest + httpx

## 코드 스타일
- Python 3.10+ (타입 힌트 필수)
- Pydantic V2 (검증 및 직렬화)
- Black (88 char), isort, flake8
- Google 스타일 docstring
- Async-first (async/await 전체 사용)

## 디렉토리 구조

/app
├── api/
│ └── v1/
│ ├── endpoints/
│ └── dependencies.py
├── core/
│ ├── config.py
│ └── security.py
├── models/
├── schemas/
├── db/
├── tasks/
└── main.py

## 명령어
```bash
uvicorn app.main:app --reload  # Dev server :8000
pytest -v --cov=app            # Tests with coverage
python -m app.tasks.consumer   # Message consumer

API 패턴

Request Validation

from pydantic import BaseModel

class CreateNotification(BaseModel):
    user_id: int
    message: str
    type: Literal["email", "sms", "push"]

Response Models

@app.post("/notifications/", response_model=NotificationResponse)
async def create_notification(data: CreateNotification):
    ...

Dependencies

async def get_current_user(token: str = Depends(oauth2_scheme)):
    ...

데이터베이스

• Async SQLAlchemy with asyncpg
• Alembic migrations (auto-generated)
• Transactions: async with context managers

테스팅

• Unit: 개별 함수 격리 테스트
• Integration: 엔드포인트 + in-memory DB
• Mock: unittest.mock.patch로 외부 서비스
• Coverage: >85% 목표

배포

• Docker: Multi-stage builds
• 환경: .env.production
• Logging: Structlog (JSON)
• Monitoring: OpenTelemetry

 

 

고급 팁

1. 파일 참조로 컨텍스트 절약

❌ Bad: 전체 코드 복사

## Component Pattern
```tsx
export function ProductCard({ product }: Props) {
  const [quantity, setQuantity] = useState(1);
  // ... 30 lines of code ...
}

**✅ Good: 파일:라인 참조**
```markdown
## Component Pattern
표준 컴포넌트 구조는 `/src/components/ProductCard.tsx`를 참조하세요.
특히 12-45 라인의 hooks 패턴과 에러 바운더리 구현을 따르세요.

2. MCP 서버 통합 가이드

## MCP (Model Context Protocol) 통합

우리 프로젝트는 다음 MCP 서버를 사용합니다:

- **github**: 이슈, PR, 커밋 관리
- **postgresql**: 개발 환경 DB 쿼리 (프로덕션 절대 금지!)
- **filesystem**: 프로젝트 파일 읽기/쓰기

불필요한 MCP 서버는 로드하지 마세요 (컨텍스트 낭비).

3. 커스텀 명령어 정의

## Custom Skills

우리 프로젝트의 커스텀 명령어:

### /deploy
스테이징 배포 전 체크리스트 실행:
1. 테스트 통과 확인
2. 린트 체크
3. 타입 에러 없음
4. 배포 스크립트 실행

### /review
코드 리뷰 모드:
- 타입 정확성
- 에러 처리
- 테스트 존재
- 권한 체크
- 성능 (N+1 쿼리 등)

4. 조건부 지침

## 컨텍스트 기반 지침

### 테스트 파일 작업 시
- 모든 엣지 케이스 커버
- `data-testid` 사용 (텍스트 의존 금지)
- 외부 API는 항상 모킹

### API 엔드포인트 작업 시
- 입력 검증 (Zod 스키마)
- 에러 처리 (try-catch)
- 권한 체크
- Rate limiting 적용

### 데이터베이스 스키마 변경 시
- 마이그레이션 파일 생성
- Rollback 전략 문서화
- 프로덕션 데이터 영향 분석

 

 

 

Best Practics

 

DO ✅

권장사항	이유
150-300줄 유지	너무 길면 중요한 정보가 묻힘
구체적으로 작성	"깔끔하게 작성"보다 "함수 최대 50줄"
실수 후 업데이트	Claude가 틀린 부분 즉시 추가
파일 참조 사용	코드 복사보다 경로:라인
프로젝트 특화	일반적인 JS 지식은 제외
버전 관리	Git으로 CLAUDE.md 관리
팀과 공유	코드 리뷰에 CLAUDE.md 포함

DON'T ❌

피해야 할 것	이유
프레임워크 문서 복사	컨텍스트 낭비, Claude는 이미 알고 있음
모든 명령어 나열	명백한 것은 제외
과도한 예시 코드	파일 참조로 대체
일반적인 조언	"좋은 코드 작성"은 무의미
업데이트 안 함	오래된 정보는 해로움
모순되는 규칙	"camelCase 사용, API는 예외"

길이 가이드라인

프로젝트 크기	권장 길이
소규모	100-150줄
중규모	150-250줄
대규모	250-400줄 + .claude/rules/ 사용
모노레포	각 패키지마다 별도 CLAUDE.md

 

 

효과 측정

성공 지표

긍정적 신호:

• ✅ Claude가 첫 시도에 프로젝트 스타일로 코드 생성
• ✅ 리뷰 단계에서 수정 사항 감소
• ✅ 명령어가 설명 없이 실행됨
• ✅ 아키텍처 결정이 의도와 일치
• ✅ 토큰 사용량 효율 증가

부정적 신호:

• ❌ Claude가 문서화된 패턴 무시
• ❌ 같은 실수 반복
• ❌ "확인 질문" 빈번
• ❌ 규칙 상충
• ❌ 명령어 실행 실패

개선 프로세스

1. 이슈 파악    → Claude가 틀린 것 기록
2. 명확화       → CLAUDE.md에 규칙 추가
3. 테스트       → 유사 작업 재시도
4. 측정         → 개선되었는지 확인
5. 정리         → 효과 없는 규칙 제거
6. 반복         → 주간 사이클

A/B 테스팅

# 방법 1: 브랜치 분리
git checkout -b test-claude-md-v2

# CLAUDE.md 수정

# 동일 작업 실행 및 비교

# 더 나은 버전 선택

비교 지표:

• 세션당 커밋 수
• 코드 리뷰 수정 횟수
• 빌드 실패 횟수
• 테스트 통과율
• 라인당 토큰 효율

 

 

 

자주 묻는 질문 (FAQ)

Q1. CLAUDE.md를 처음 만들 때 어디서 시작하나요?

A: Claude Code에 내장된 명령어 사용:

claude /init

기본 템플릿이 생성되며, 이를 바탕으로 프로젝트에 맞게 수정하세요.

Q2. 너무 길어지는 것 같아요. 어떻게 줄이나요?

A: 3가지 전략:

1. 프레임워크 상식 제거: Claude는 React/Next.js를 이미 알고 있음
2. 파일 참조 사용: 코드 복사 대신 경로 제공
3. 모듈화: .claude/rules/로 분리

목표: 150-300줄

Q3. 팀원마다 다른 의견이 있어요.

A: CLAUDE.md를 코드 리뷰 대상에 포함하세요. 팀 컨벤션 논의의 중심 문서로 활용하면 됩니다.

Q4. 얼마나 자주 업데이트해야 하나요?

A:

• 즉시: Claude가 실수할 때마다
• 정기적: 주 1회 또는 분기 1회 검토
• 변경 시: 아키텍처 또는 주요 패턴 변경 시

Q5. 모노레포에서는 어떻게 관리하나요?

A:

monorepo/
├── CLAUDE.md           # 전체 프로젝트 공통
└── packages/
    ├── api/
    │   └── CLAUDE.md   # API 패키지 전용
    └── web/
        └── CLAUDE.md   # Web 패키지 전용

각 패키지마다 별도 CLAUDE.md를 두고, 루트에는 공통 규칙만 작성.

Q6. CLAUDE.md가 실제로 효과가 있는지 어떻게 알 수 있나요?

A: 3가지 테스트:

1. CLAUDE.md 없이 작업 → 얼마나 많은 설명이 필요한가?
2. CLAUDE.md와 함께 작업 → 첫 시도 성공률은?
3. 코드 리뷰 피드백 수 → 줄어들었나?

Q7. 보안 관련 정보를 CLAUDE.md에 포함해도 되나요?

A: API 키나 비밀번호는 절대 안 됩니다. 보안 "원칙"과 "규칙"만 포함:

## 보안
- API 키는 환경 변수로만 관리
- 사용자 입력은 항상 검증 (Zod)
- OWASP Top 10 준수

Q8. 다른 프로젝트의 CLAUDE.md를 참고할 수 있나요?

A: 네! 다음 리소스 참고:

• Awesome Claude Code
• CLAUDE.md Templates
• Next.js + TypeScript 예시

 

 

 

시작하기 템플릿

미니멀 템플릿 (소규모 프로젝트)

# [프로젝트 이름]

## 개요
[1-2줄로 프로젝트 설명]

## 기술 스택
- [언어/프레임워크]
- [주요 라이브러리]

## 명령어
```bash
npm run dev        # 개발 서버
npm test           # 테스트
npm run build      # 빌드

코드 스타일

• [주요 컨벤션 3-5개]

디렉토리 구조

• /src - [설명]
• /tests - [설명]

 

표준 템플릿 (중규모 프로젝트)

# [프로젝트 이름]

## 프로젝트 컨텍스트
[2-3줄 설명 + 팀 규모]

## 기술 스택
[Frontend, Backend, Database, Testing으로 구분]

## 코드 스타일
[TypeScript/Python 규칙, 네이밍, 파일 구조]

## 디렉토리 구조
[주요 폴더 설명]

## 아키텍처 패턴
[사용하는 디자인 패턴]

## 테스팅
[테스트 요구사항 및 커버리지]

## 보안
[주요 보안 원칙]

## 명령어
[개발, 테스트, 배포 명령어]

## 주의사항
[자주 발생하는 실수 또는 주의점]

엔터프라이즈 템플릿 (대규모 프로젝트)

루트 CLAUDE.md + .claude/rules/ 모듈화

CLAUDE.md (메인):

# [프로젝트 이름]

## 개요
[상세 설명]

## 기술 스택
[상세 스택]

## 아키텍처
[고수준 아키텍처]

## 모듈별 규칙
상세 규칙은 `.claude/rules/` 디렉토리를 참조하세요:
- code-style.md
- testing.md
- security.md
- frontend/components.md
- backend/api.md

.claude/rules/code-style.md:

# 코드 스타일 가이드

[상세한 코딩 컨벤션]

.claude/rules/testing.md:

# 테스팅 가이드

[상세한 테스트 전략]

 

 

 

다음 단계

실행하기

1단계: 기본 파일 생성

claude /init

2단계: 프로젝트에 맞게 수정

• 기술 스택 업데이트
• 주요 컨벤션 추가
• 명령어 작성

3단계: 테스트

claude

> "새로운 컴포넌트를 만들어줘"

(CLAUDE.md를 따르는지 확인)

4단계: 개선

• Claude가 틀린 부분 기록
• CLAUDE.md에 규칙 추가
• 다시 테스트

추천 리소스

• Claude Code Best Practices
• CLAUDE.md Complete Guide
• Awesome Claude Code
• CLAUDE.md Templates

결론 - 프로젝트 전용 AI 만들기

CLAUDE.md는 Claude Code를 범용 도구에서 프로젝트 전문가로 변모시킵니다.

핵심 요약:

1.  세션마다 반복 설명 불필요 (토큰 절약)
2.  일관된 코드 품질 자동 유지
3.  팀 컨벤션 문서화 및 공유
4.  신규 팀원 온보딩 가속화
5.  150-300줄로 간결하게 유지
6.  지속적 개선으로 효과 극대화

시작하기:

claude /init

이제 프로젝트의 CLAUDE.md를 작성하고 Claude를 당신만의 전용 AI 개발자로 만드세요! 🚀

---

📌 이 시리즈의 완결편입니다!
전체 시리즈를 확인하세요:

• 1편 : Claude API 시작하기 - API 키 발급부터 첫 호출까지 완벽 가이드 (2026)
• 2편: Claude API 모델 비교 가이드
• 3편: Claude API Python SDK 완벽 가이드
• 4편: Claude API 요금제 & 비용 최적화 전략
• 5편: Claude API Tool Use 구현하기
• 6편: Claude Code 설치 및 시작하기
• 7편: Claude Code 핵심 명령어 총정리
• 8편: Claude Code VS Code 연동
• 9편: Claude Code MCP 서버 설정법
• 10편: Claude Code 리팩토링 & 디버깅 실전
• 11편: Claude Code GitHub Actions 자동화

[Claude] Claude Code VS Code 연동 - 개발환경 세팅 가이드

 

[Claude] Claude Code MCP 서버 설정법 - GitHub, 파일시스템 연동

 

[Claude] Claude Code로 코드 리팩토링 & 디버깅 실전 예제

 

[Claude] Claude Code GitHub Actions 자동화 - PR 자동 리뷰 설정

 

🔗 참고 자료:

• Claude Code Best Practices
• The Complete Guide to CLAUDE.md
• Awesome Claude Code