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줄 이내"처럼 구체적으로
예제 포함: 좋은 예시와 나쁜 예시를 보여주세요

다음 단계

슬래시 명령어 - 자주 사용하는 작업을 단축키로 만드세요
스킬 시스템 - 복잡한 작업을 자동화하세요
설정 및 환경변수 - 더 많은 커스터마이징 옵션

이 섹션이 도움이 되셨나요?

CLAUDE.md 설정

읽는 시간: 8분 | 난이도: 중급

이 섹션에서는 CLAUDE.md 파일을 사용하여 Claude Code의 동작을 프로젝트에 맞게 커스터마이징하는 방법을 알아봅니다.

CLAUDE.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 (테스트)

## 코딩 규칙

### 프로젝트 구조


### 네이밍 컨벤션
- 클래스: 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줄 이내"처럼 구체적으로
예제 포함: 좋은 예시와 나쁜 예시를 보여주세요

다음 단계

슬래시 명령어 - 자주 사용하는 작업을 단축키로 만드세요
스킬 시스템 - 복잡한 작업을 자동화하세요
설정 및 환경변수 - 더 많은 커스터마이징 옵션

이 섹션이 도움이 되셨나요?

CLAUDE.md 설정

CLAUDE.md란 무엇인가요?

핵심 기능

기본 구조

파일 위치

기본 템플릿

상세 설정 예시

1. 프론트엔드 프로젝트 (React + TypeScript)

2. 백엔드 프로젝트 (FastAPI + Python)

고급 기능

1. 훅(Hooks) 통합

2. 멀티 모듈 프로젝트

3. 환경별 설정

모범 사례

좋은 CLAUDE.md

피해야 할 것

팁

다음 단계

관련 가이드

CLAUDE.md 설정

CLAUDE.md란 무엇인가요?

핵심 기능

기본 구조

파일 위치

기본 템플릿

상세 설정 예시

1. 프론트엔드 프로젝트 (React + TypeScript)

2. 백엔드 프로젝트 (FastAPI + Python)

고급 기능

1. 훅(Hooks) 통합

2. 멀티 모듈 프로젝트

3. 환경별 설정

모범 사례

좋은 CLAUDE.md

피해야 할 것

팁

다음 단계

관련 가이드