CLAUDE.md 파일 구성 가이드

# 프로젝트 이름

## 프로젝트 개요

[프로젝트 목적, 핵심 기능 및 대상 사용자에 대한 간략한 설명]

## 기술 스택

- 프론트엔드: [프레임워크 및 주요 라이브러리]
- 백엔드: [언어 및 프레임워크]
- 데이터베이스: [데이터베이스 유형]
- 배포: [배포 플랫폼]

## 프로젝트 구조

\```
project/
├── src/ # 소스 코드
├── tests/ # 테스트 파일
├── docs/ # 문서
└── scripts/ # 스크립트 파일
\```

## 개발 표준

[프로젝트별 코딩 표준]

## 주의사항

[프로젝트별 주의사항 및 제한사항]

# CLAUDE.md - 프로젝트 구성 파일

## 일반 규칙 (모든 프로젝트 필수)

### 커뮤니케이션 언어

- 항상 간체 중국어를 사용하여 생각하고 대화
- 코드 주석은 영어, 문서는 중국어

### 문서 관리

- 공식 문서는 `docs/` 디렉터리에
- 토론 제안은 `discuss/` 디렉터리에
- README는 간결하게 유지, 상세 문서는 별도 보관

## 코드 아키텍처 표준

### 파일 크기 제한

- Python/JavaScript/TypeScript: 각 파일 최대 300줄
- Java/Go/Rust: 각 파일 최대 400줄
- 폴더당 파일 8개 이하
- 초과 시 리팩토링 또는 분할 필요

### 코드 품질 지표

다음 코드 냄새를 피하세요:

1. **경직성**: 시스템 변경이 어려움
2. **중복성**: 중복 코드가 너무 많음
3. **순환 종속성**: 모듈 간 상호 의존
4. **취약성**: 변경이 연쇄 문제를 일으킴
5. **모호성**: 코드 의도가 불명확
6. **데이터 덩어리**: 데이터 항목이 항상 함께 나타남
7. **과도한 설계**: 불필요한 복잡성

## 기술 스택 제약 조건

### 프론트엔드 기술 스택

- React 19+ (버전 18 이하 사용 금지)
- Next.js 15.4+ (버전 14 이하 사용 금지)
- Tailwind CSS v4 (v3 사용 금지)
- TypeScript 우선, JavaScript 피하기
- CommonJS 금지, ES Modules만 사용

### 백엔드 기술 스택

- Node.js 18+
- TypeScript 사용
- Express/Fastify를 웹 프레임워크로 사용
- Prisma를 ORM으로 사용

### Python 프로젝트

- 종속성 관리에 uv 사용 (pip/poetry/conda 사용 금지)
- 가상 환경 디렉터리 이름: `.venv`
- 강력한 타입 정의, dict 사용 피하기
- 프로젝트 루트 디렉터리 깔끔하게 유지

## 개발 워크플로우

### 스크립트 관리

- 모든 스크립트는 `scripts/` 디렉터리에
- 시작-중지 작업에 `.sh` 스크립트 사용
- npm/pnpm/python 명령 직접 사용 금지
- 스크립트 실패 시 즉시 수정 필요

### 로그 관리

- 구성 파일이 로그 출력
- `logs/` 디렉터리에 통합 출력
- 타임스탬프 및 로그 레벨 포함
- 오류 로그 별도 저장

### 테스트 요구사항

- 단위 테스트 커버리지 > 80%
- 중요 기능은 통합 테스트 필수
- 테스트 파일은 `tests/` 디렉터리에
- CI/CD를 사용하여 자동으로 테스트 실행

## 명명 규칙

### 파일 이름

- 컴포넌트: PascalCase (예: UserProfile.tsx)
- 유틸리티 함수: camelCase (예: formatDate.ts)
- 상수 파일: UPPER_SNAKE_CASE (예: API_CONSTANTS.ts)
- 스타일 파일: kebab-case (예: user-profile.css)

### 변수 이름

- 변수/함수: camelCase
- 상수: UPPER_SNAKE_CASE
- 클래스/인터페이스: PascalCase
- 비공개 속성: \_camelCase

## Git 워크플로우

### 브랜치 전략

- main: 프로덕션 코드
- develop: 개발 코드
- feature/\*: 기능 브랜치
- hotfix/\*: 긴급 수정 브랜치

### 커밋 규칙

- feat: 새로운 기능
- fix: 버그 수정
- docs: 문서 업데이트
- style: 코드 포맷팅
- refactor: 코드 리팩토링
- test: 테스트 관련
- chore: 빌드/도구 변경

## API 설계 표준

### RESTful 원칙

- GET: 리소스 가져오기
- POST: 리소스 생성
- PUT: 리소스 업데이트 (전체)
- PATCH: 리소스 업데이트 (부분)
- DELETE: 리소스 삭제

### 응답 형식

\```json
{
"success": true,
"data": {},
"message": "작업 성공",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### 오류 처리

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "오류 설명",
"details": {}
}
}
\```

## 보안 표준

### 민감한 정보

- 코드에 키를 하드코딩하지 않기
- 구성 관리에 환경 변수 사용
- `.env` 파일을 Git에 커밋하지 않기
- 정기적으로 종속성 업데이트

### 데이터 검증

- 프론트엔드와 백엔드 모두 데이터 검증
- 스키마 검증 라이브러리 사용 (예: zod)
- SQL 쿼리 매개변수화
- XSS 및 CSRF 공격 방지

## 성능 최적화

### 프론트엔드 최적화

- 이미지 지연 로딩
- 코드 분할
- 캐싱 전략
- 가상 스크롤 (큰 목록)

### 백엔드 최적화

- 데이터베이스 쿼리 최적화
- 캐시 사용 (Redis)
- API 응답 압축
- 동시성 제어

## 배포 구성

### 환경 변수

- development: 개발 환경
- staging: 테스트 환경
- production: 프로덕션 환경

### 컨테이너화

- 배포에 Docker 사용
- 다단계 빌드로 이미지 크기 최적화
- 서비스 오케스트레이션에 docker-compose 사용

## 모니터링 및 로그

### 모니터링 지표

- API 응답 시간
- 오류율
- 리소스 사용률
- 사용자 행동 분석

### 로그 레벨

- ERROR: 오류 정보
- WARN: 경고 정보
- INFO: 일반 정보
- DEBUG: 디버그 정보

## 특별 주의사항

⚠️ **중요 알림**:

1. 코드 문제 발견 시 즉시 제기
2. 불확실할 때 사용자에게 적극적으로 질문
3. 코드를 깨끗하고 유지 관리 가능하게 유지
4. 기존 프로젝트 표준 준수

## React/Next.js 프로젝트 표준

### 컴포넌트 표준

- 함수형 컴포넌트 + Hooks 사용
- 컴포넌트 파일은 컴포넌트와 동일한 이름
- 파일 하나에 컴포넌트 하나
- Props는 TypeScript 인터페이스로 정의

### 상태 관리

- 간단한 상태: useState
- 복잡한 상태: useReducer
- 전역 상태: Context API / Zustand
- 서버 상태: TanStack Query

### 스타일링 솔루션

- Tailwind CSS v4를 주로 사용
- CSS Modules를 보조로 사용
- 인라인 스타일 피하기
- 반응형 디자인 우선

### 성능 최적화

- React.memo를 사용하여 불필요한 렌더링 방지
- useMemo/useCallback로 계산 최적화
- 동적 import로 코드 분할 구현
- 이미지에 next/image 컴포넌트 사용

## Python 프로젝트 표준

### 프로젝트 구조

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### 종속성 관리

- 모든 종속성에 uv 사용
- pyproject.toml로 프로젝트 구성 정의
- requirements.txt는 프로덕션 배포용
- requirements-dev.txt는 개발 종속성용

### 타입 주석

- 모든 함수에 타입 주석 필수
- 데이터 구조 정의에 dataclass 사용
- mypy와 함께 타입 검사
- Any 타입 사용 피하기

### 비동기 프로그래밍

- async/await 우선 사용
- asyncio를 사용한 동시성 관리
- 데이터베이스 작업에 비동기 드라이버 사용
- HTTP 요청에 httpx 사용

## 마이크로서비스 아키텍처 표준

### 서비스 분할

- 비즈니스 도메인별로 서비스 분할
- 각 서비스는 독립적으로 배포
- 서비스 간 API를 통한 통신
- 패키지 관리를 통한 공유 코드

### API 게이트웨이

- 통합 진입점 관리
- 인증 및 권한 부여
- 속도 제한 및 회로 차단
- 요청 라우팅

### 서비스 통신

- HTTP/REST: 동기 호출
- 메시지 큐: 비동기 통신
- gRPC: 고성능 시나리오
- WebSocket: 실시간 통신

### 데이터 관리

- 각 서비스는 독립적인 데이터베이스
- 서비스 간 트랜잭션 피하기
- 이벤트 기반으로 일관성 유지
- 멱등성 작업 구현

> /init