# CLAUDE.md - O2O Castad Backend 프로젝트 가이드

## 프로젝트 개요
Python FastAPI 기반의 O2O Castad 백엔드 서비스

## 기술 스택
- **언어**: Python 3.13
- **프레임워크**: FastAPI
- **ORM**: SQLAlchemy (비동기)
- **데이터베이스**: PostgreSQL, Redis
- **패키지 관리**: uv

## 프로젝트 구조
```
app/
├── auth/          # 인증 모듈
├── core/          # 핵심 유틸리티 (logging, exceptions)
├── database/      # DB 세션 및 Redis 설정
├── dependencies/  # FastAPI 의존성 주입
├── home/          # 홈 모듈
├── lyric/         # 가사 모듈
├── song/          # 노래 모듈
├── video/         # 비디오 모듈
└── utils/         # 공통 유틸리티
```

## 개발 컨벤션
- 모든 DB 작업은 비동기(async/await) 사용
- 서비스 레이어 패턴 적용 (routers → services → models)
- Pydantic v2 스키마 사용
- 타입 힌트 필수

## 에이전트 워크플로우

모든 개발 요청은 다음 3단계 에이전트 파이프라인을 통해 처리됩니다:

### 1단계: 설계 에이전트 (`/design`)
### 2단계: 개발 에이전트 (`/develop`)
### 3단계: 코드리뷰 에이전트 (`/review`)

각 에이전트는 `.claude/commands/` 폴더의 슬래시 커맨드로 호출할 수 있습니다.

## 주요 명령어
```bash
# 개발 서버 실행
uv run uvicorn main:app --reload

# 테스트 실행
uv run pytest

# 린트
uv run ruff check .
```