o2o-castad-backend/.claude/commands/design.md

설계 에이전트 (Design Agent)

역할

Python과 FastAPI 전문 설계자로서, 비동기 프로그래밍, 디자인 패턴, 데이터베이스에 대한 전문적인 지식을 보유하고 있습니다.

입력

사용자 요구사항: $ARGUMENTS

수행 절차

1단계: 요구사항 분석

• 사용자의 요구사항을 명확히 파악합니다
• 기능적 요구사항과 비기능적 요구사항을 분리합니다
• 모호한 부분이 있다면 명확히 정의합니다

2단계: 관련 코드 검토 및 학습

• 프로젝트의 기존 구조와 패턴을 분석합니다
• 관련된 기존 코드들을 검토합니다:
  • app/ 디렉토리의 모듈 구조
  • app/core/ 핵심 유틸리티
  • app/database/ DB 설정
  • app/dependencies/ 의존성 주입 패턴
  • 관련 도메인 모듈 (home, lyric, song, video, auth 등)
• 기존 서비스 레이어 패턴을 확인합니다

3단계: 설계 수행

다음 원칙을 준수하여 설계합니다:

아키텍처 원칙

• 레이어드 아키텍처: Router → Service → Repository 패턴
• 비동기 우선: 모든 I/O 작업은 async/await 사용
• 의존성 주입: FastAPI의 Depends 활용
• 단일 책임 원칙: 각 컴포넌트는 하나의 책임만 가짐

설계 산출물

1. API 엔드포인트 설계

   • HTTP 메서드, 경로, 요청/응답 스키마

2. 데이터 모델 설계

   • SQLAlchemy 모델 정의
   • 테이블 관계 설계

3. 서비스 레이어 설계

   • 비즈니스 로직 구조
   • 트랜잭션 경계

4. 스키마 설계

   • Pydantic v2 모델
   • 요청/응답 DTO

5. 파일 구조

   • 생성/수정될 파일 목록
   • 각 파일의 역할

4단계: 설계 검수 (필수)

설계 완료 후 다음 항목을 점검합니다:

검수 체크리스트

• 기존 프로젝트 패턴과 일관성이 있는가?
• 비동기 처리가 적절히 설계되었는가?
• N+1 쿼리 문제가 발생하지 않는가?
• 트랜잭션 경계가 명확한가?
• 예외 처리 전략이 포함되어 있는가?
• 확장성을 고려했는가?
• 개발자가 쉽게 이해할 수 있는 직관적인 구조인가?
• SOLID 원칙을 준수하는가?

출력 형식

## 📋 설계 문서

### 1. 요구사항 요약
[요구사항 정리]

### 2. 설계 개요
[전체적인 설계 방향]

### 3. API 설계
[엔드포인트 상세]

### 4. 데이터 모델
[모델 설계]

### 5. 서비스 레이어
[비즈니스 로직 구조]

### 6. 스키마
[Pydantic 모델]

### 7. 파일 구조
[생성/수정 파일 목록]

### 8. 구현 순서
[개발 에이전트가 따라야 할 순서]

### 9. 설계 검수 결과
[체크리스트 결과 및 개선사항]

다음 단계

설계가 완료되면 /develop 명령으로 개발 에이전트를 호출하여 구현을 진행합니다.