CLAUDE.md 설정
읽는 시간: 8분 | 난이도: 중급
이 섹션에서는 CLAUDE.md 파일을 사용하여 Claude Code의 동작을 프로젝트에 맞게 커스터마이징하는 방법을 알아봅니다.
CLAUDE.md란 무엇인가요?
CLAUDE.md는 프로젝트 루트에 배치하는 특별한 파일로, Claude Code에게 프로젝트에 대한 맥락과 지침을 제공합니다. GitHub의 .github/copilot-instructions.md와 유사하지만 더 강력합니다.
핵심 기능
프로젝트 컨텍스트
- 프로젝트 구조 설명
- 사용하는 프레임워크와 라이브러리
- 코딩 규칙과 스타일 가이드
동작 지침
- Claude가 어떻게 응답해야 할지 명시
- 선호하는 패턴과 안티패턴
- 프로젝트 특정 용어 정의
워크플로우 자동화
- 자주 사용하는 명령어 단축키
- 테스트 실행 방법
- 배포 프로세스
기본 구조
파일 위치
my-project/
├── .claude/
│ └── CLAUDE.md # 프로젝트 전체 설정
├── src/
├── tests/
└── CLAUDE.md # 워킹 디렉토리 설정 (선택)
기본 템플릿
# 프로젝트 이름
## 프로젝트 개요
[프로젝트에 대한 간단한 설명]
## 기술 스택
- 주요 언어와 프레임워크
- 주요 라이브러리
## 코딩 규칙
- 코드 스타일 가이드
- 네이밍 컨벤션
- 파일 구조 규칙
## 테스트
- 테스트 프레임워크
- 테스트 실행 방법
## 빌드 및 배포
- 빌드 명령어
- 배포 프로세스
상세 설정 예시
1. 프론트엔드 프로젝트 (React + TypeScript)
# E-Commerce Dashboard
## 프로젝트 개요
React와 TypeScript로 구축된 전자상거래 대시보드입니다.
관리자가 제품, 주문, 고객을 관리할 수 있습니다.
## 기술 스택
- React 18 + TypeScript
- Tailwind CSS (디자인 시스템)
- React Query (데이터 페칭)
- React Hook Form (폼 관리)
- Vitest (테스트)
## 코딩 규칙
### 컴포넌트 구조
src/components/ ├── ui/ # 재사용 가능한 UI 컴포넌트 ├── features/ # 기능별 컴포넌트 └── layouts/ # 레이아웃 컴포넌트
### 네이밍 컨벤션
- 컴포넌트: PascalCase (UserCard.tsx)
- 유틸리티: camelCase (formatDate.ts)
- 타입: PascalCase + 'T' 접두사 (TUser, TOrder)
- 상수: UPPER_SNAKE_CASE (API_BASE_URL)
### 코드 스타일
- 함수 컴포넌트만 사용 (클래스 컴포넌트 금지)
- props 인터페이스는 컴포넌트 내부에 정의
- 커스텀 훅은 'use' 접두사 사용
### 가져오기 순서
1. React 관련
2. 외부 라이브러리
3. 내부 컴포넌트
4. 타입
5. 유틸리티
6. 스타일
## 테스트
- 테스트 파일: *.test.tsx
- 실행: npm run test
- 커버리지: npm run test:coverage
## 빌드 및 배포
- 개발: npm run dev
- 빌드: npm run build
- 프리뷰: npm run preview
- 배포: Vercel에 자동 배포
## 중요: 스타일 가이드
- Tailwind 유틸리티 클래스 우선
- 복잡한 스타일만 css-modules 사용
- 다크 모드 지원 필수
2. 백엔드 프로젝트 (FastAPI + Python)
# API Server
## 프로젝트 개요
FastAPI로 구축된 REST API 서버입니다.
인증, 데이터베이스, 캐싱을 포함합니다.
## 기술 스택
- Python 3.11+
- FastAPI
- SQLAlchemy (ORM)
- Pydantic (데이터 검증)
- PostgreSQL (데이터베이스)
- Redis (캐싱)
- pytest (테스트)
## 코딩 규칙
### 프로젝트 구조
src/ ├── api/ # API 엔드포인트 ├── models/ # SQLAlchemy 모델 ├── schemas/ # Pydantic 스키마 ├── services/ # 비즈니스 로직 ├── core/ # 설정, 의존성 └── utils/ # 유틸리티
### 네이밍 컨벤션
- 클래스: PascalCase (UserService)
- 함수/변수: snake_case (get_user, user_id)
- 상수: UPPER_SNAKE_CASE (MAX_RETRIES)
- 파일: snake_case (user_service.py)
### API 설계 규칙
- 엔드포인트는 kebab-case: `/api/v1/users/{id}`
- 성공 응답: 200 OK
- 생성: 201 Created
- 검증 오류: 422 Unprocessable Entity
- 서버 오류: 500 Internal Server Error
### 비동기 처리
- DB 쿼리는 항상 async 사용
- 외부 API 호출은 async 사용
- I/O 작업은 asyncio 사용
## 데이터베이스
- 마이그레이션: alembic
- 시드: npm run db:seed
- 리셋: npm run db:reset
## 테스트
- 단위 테스트: tests/unit/
- 통합 테스트: tests/integration/
- 실행: pytest
- 커버리지: pytest --cov
## 보안 규칙
- 모든 엔드포인트는 인증 필요 (제외된 경우 명시)
- 민감 정보는 환경변수로 관리
- SQL 인젝션 방지를 위해 ORM 사용
- 입력 검증은 Pydantic으로
## 중요: 오류 처리
- 서비스 계층에서 커스텀 예외 발생
- API 계층에서 적절한 HTTP 상태 코드 변환
- 로그에는 스택 트레이스 포함
- 응답에는 사용자 친화적 메시지
고급 기능
1. 훅(Hooks) 통합
CLAUDE.md와 훅을 함께 사용하여 더 강력한 자동화를 구현할 수 있습니다.
# 프로젝트 설정
## 사전 커밋 훅
- eslint: 자동 수정 및 린트
- prettier: 코드 포맷팅
- tsc: 타입 검사
## 커밋 메시지 규칙
컨벤셔널 커밋 사용:
- feat: 새로운 기능
- fix: 버그 수정
- docs: 문서 변경
- refactor: 리팩토링
2. 멀티 모듈 프로젝트
모노레포나 멀티 모듈 프로젝트에서는 각 모듈에 CLAUDE.md를 배치할 수 있습니다.
project/
├── .claude/CLAUDE.md # 전역 설정
├── packages/
│ ├── frontend/CLAUDE.md # 프론트엔드 설정
│ ├── backend/CLAUDE.md # 백엔드 설정
│ └── shared/CLAUDE.md # 공유 코드 설정
3. 환경별 설정
# 프로젝트 설정
## 개발 환경
- 핫 리로드 활성화
- 상세 로그 출력
- 테스트 데이터 사용
## 프로덕션 환경
- 최적화 활성화
- 에러 로그만 출력
- 실제 데이터베이스 사용
## Claude가 알아야 할 것
- 현재 환경은 NODE_ENV 환경변수로 확인
- 개발일 때는 더 상세한 설명 제공
- 프로덕션일 때는 보안에 더 주의
모범 사례
좋은 CLAUDE.md
# 프로젝트 이름
## 개요
한 문장으로 프로젝트 설명
## 기술 스택
불렛 포인트로 핵심 기술 나열
## 규칙
구체적이고 실행 가능한 지침
피해야 할 것
# 프로젝트
대단히 긴 설명...
(너무 길면 Claude가 집중하지 못함)
불명확한 지침...
"좋은 코드를 작성하세요" → 무슨 의미인지 모름
팁
- 점진적 업데이트: 프로젝트가 발전함에 따라 CLAUDE.md도 업데이트하세요
- 팀과 공유: CLAUDE.md를 버전 관리에 포함하여 팀 전체가 혜택을 받게 하세요
- 구체적이게 될 때까지: "좋은 코드" 대신 "함수는 20줄 이내"처럼 구체적으로
- 예제 포함: 좋은 예시와 나쁜 예시를 보여주세요
다음 단계
이 섹션이 도움이 되셨나요?