o2o-castad-backend/CLAUDE.md

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

프로젝트 개요

Python FastAPI 기반의 O2O Castad 백엔드 서비스

기술 스택

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

프로젝트 구조

app/
├── core/          # 핵심 유틸리티 (logging, exceptions)
├── database/      # DB 세션 및 Redis 설정
├── dependencies/  # FastAPI 의존성 주입
├── home/          # 홈 모듈 (크롤링, 이미지 업로드)
├── user/          # 사용자 모듈 (카카오 로그인, JWT 인증)
├── lyric/         # 가사 모듈
├── song/          # 노래 모듈
├── video/         # 비디오 모듈
└── utils/         # 공통 유틸리티

개발 컨벤션

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

에이전트 워크플로우

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

1단계: 설계 에이전트 (/design)

2단계: 개발 에이전트 (/develop)

3단계: 코드리뷰 에이전트 (/review)

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

주요 명령어

# 개발 서버 실행
uv run uvicorn main:app --reload

# 테스트 실행
uv run pytest

# 린트
uv run ruff check .