CLAUDE.md: Claude Code의 핵심 설정 파일

CLAUDE.md는 Claude Code를 효과적으로 사용하기 위한 가장 중요한 파일입니다. 이 파일은 에이전트의 "헌법"으로, 특정 저장소가 어떻게 동작하는지에 대한 주요 정보원 역할을 합니다.

CLAUDE.md란?

  • 위치: 프로젝트 루트 디렉토리
  • 역할: Claude의 영구 메모리로, 세션 시작 시 자동으로 로드됩니다.
  • 목적: 프로젝트별 규칙, 코딩 스타일, 아키텍처 결정사항을 Claude에게 전달

CLAUDE.md 작성 원칙

1. 간결성 유지

# 권장 크기
- 소규모 프로젝트: 2-5KB
- 대규모 엔터프라이즈 저장소: 최대 13KB

# 포함 기준
- 30% 이상의 엔지니어가 사용하는 도구만 문서화
- 포괄적인 문서가 아닌 핵심 가이드라인만 포함

2. 권장 구조

# CLAUDE.md

## 프로젝트 개요
[프로젝트에 대한 간단한 설명]

## 기술 스택
- 언어: TypeScript
- 프레임워크: Next.js 14
- 데이터베이스: PostgreSQL
- ORM: Prisma

## 빌드 명령어
```bash
npm install          # 의존성 설치
npm run dev          # 개발 서버
npm run build        # 프로덕션 빌드
npm run test         # 테스트 실행
```

## 코딩 컨벤션
- 함수명: camelCase
- 컴포넌트: PascalCase
- 상수: UPPER_SNAKE_CASE

## 아키텍처 결정사항
- API 엔드포인트는 /api 디렉토리에 위치
- 상태 관리는 Zustand 사용
- 에러 핸들링은 try-catch + 커스텀 에러 클래스

## 주의사항
- 절대 프로덕션 데이터베이스에 직접 쿼리 금지
- 모든 API 요청에 인증 토큰 필수

3. 피해야 할 패턴

  • 부정적 제약 조건 사용 금지: "X를 절대 사용하지 마세요" 대신 대안을 항상 제시
  • @-file 문서화 피하기: 컨텍스트를 과도하게 사용하므로, 왜/언제 읽어야 하는지 설명만 포함
  • 포괄적 매뉴얼 작성 금지: 가드레일 중심의 간결한 지침 유지

계층적 CLAUDE.md 구조

Claude Code는 여러 위치의 CLAUDE.md를 지원합니다:

# 로드 순서 (우선순위 낮은 것부터)
1. ~/.claude/CLAUDE.md          # 전역 설정 (모든 프로젝트에 적용)
2. /project/CLAUDE.md           # 프로젝트 루트 설정
3. /project/src/CLAUDE.md       # 서브디렉토리 설정 (해당 디렉토리 작업시)

전역 vs 프로젝트 CLAUDE.md

구분위치용도
전역 설정~/.claude/CLAUDE.md개인 선호도, 공통 도구 설정
프로젝트 설정프로젝트 루트팀 공유 규칙, 프로젝트별 아키텍처
모듈 설정서브디렉토리특정 모듈의 세부 규칙

실제 사용 예시

React 프로젝트 예시

# CLAUDE.md

## 프로젝트: E-commerce Platform

## 컴포넌트 구조
- /components/ui: 재사용 가능한 UI 컴포넌트 (Button, Input, Modal 등)
- /components/features: 비즈니스 로직 포함 컴포넌트
- /components/layouts: 페이지 레이아웃 컴포넌트

## 상태 관리 규칙
- 전역 상태: Zustand store (/stores 디렉토리)
- 서버 상태: TanStack Query
- 로컬 상태: useState (단순한 경우만)

## API 호출 패턴
모든 API 호출은 /lib/api 디렉토리의 함수 사용
```typescript
// 올바른 패턴
import { getProducts } from "@/lib/api/products";

// 피해야 할 패턴 (직접 fetch 사용 금지)
fetch("/api/products")
```

## 테스트 규칙
- 유틸리티 함수: 단위 테스트 필수
- 컴포넌트: React Testing Library 사용
- E2E: Playwright 사용

CLAUDE.md 최적화 팁

  1. 내부 도구 단순화의 강제 기능으로 활용: CLAUDE.md 작성이 어렵다면 도구가 너무 복잡하다는 신호
  2. 주기적 검토: 분기별로 업데이트하여 최신 상태 유지
  3. 팀 피드백 수집: Claude가 자주 실수하는 부분을 CLAUDE.md에 추가
  4. 버전 관리: Git으로 변경 이력 추적

참고 자료: