Task 1 (데이터구조) Task 2 (용어표준화) Task 3 (변경영향) Mission 1 (의사결정) Mission 2 (예외시나리오) 📊 요약 보기 ← 강의실
Day 4 Mission 01 의사결정 로깅

Mission 01. 설계 API 리뷰 및 개선 (Design Decision Log)

데이터베이스 정규화 방식 및 아키텍처 의결 사항을 기록하는 표준 Design Decision Log(Why) 보고서를 자동 작성합니다.

Mission 1 설계 API 리뷰 및 개선 실습 가이드

📥 실습 입력 (Input)

  • • day4_api_review_dialogue.md (회의 대화 기록)

💾 실습 출력 (Output)

  • • design-decision-log.md (API 리뷰 및 개선 문서)

1. 스토리 및 실습 배경

처음 빌드한 스타트업의 API 문서를 본 외부 아키텍처 자문가가 지적합니다. "URL 구조가 `/api/v1/getUsers` 처럼 동사로 되어 있고, 에러 발생 시 HTTP Status는 200 Ok로 준 채 Response Body 안에 에러 메시지를 넣어 보내고 있군요. 그리고 리소스를 수정할 때 PUT과 PATCH를 혼용하고 있습니다. 이 구조는 확장성과 범용 개발자 도구 규격을 준수하지 못해 추후 고도화 시 막대한 리팩토링 비용을 부릅니다."

설계 초기 단계에서 표준적인 API 설계 철학과 스타일 규칙(REST API 표준, 명명 규칙, 일관된 예외 규격)을 준수하지 않으면, 외부 연동(Payment PG, 외부 파트너십) 시 개발 장벽을 야기합니다.

이번 미션에서는 기술설계 단계에서 진행된 데이터 정규화 및 아키텍처 의결 배경을 Codex를 활용해 정형화된 Design Decision Log 문서로 작성하여, 시스템의 역사적 자산과 설계 근거(Why)를 안전하게 관리하는 법을 배웁니다.

2. 학습 목표

  • 회의록에서 정규화 및 데이터베이스 구조 설계 결정을 정확하게 추출할 수 있다.
  • 의결 항목, 배경 사유, 대안 검토, 승인자, 향후 변경 가능성을 명문화할 수 있다.
  • 설계 의사결정의 역사(Why)를 기록하여 신규 팀원의 중복 회의와 실수를 예방할 수 있다.

🛠️ 실제 따라 하기 실습 가이드

  1. 실습용 파일 생성: 아래 다운로드 버튼을 눌러 API 명세서 초안 및 리뷰 회의 대화록 파일을 automation/ 폴더 내에 저장합니다.
  2. Codex 로깅 위임: Codex Client 프롬프트 입력창에 아래 **Codex 요청 프롬프트**를 전송하여 빌드합니다.
  3. 로그 점검: 출력된 리포트에서 결정 ID(DEC-003), 의결 배경, 검토 대안(기각 사유), 승인 주체가 정확히 구조화되었는지 검토합니다.

실습 자료 다운로드 (2개 파일)

Codex 요청 프롬프트

Mission 01 Prompt
제공된 day4_api_specification_v1.md의 API 명세서를 검토하여, REST API 설계 표준(HTTP Method 용도, URL 명명법), 일관된 오류 처리 구조, 확장성을 기준으로 개선점을 분석하고 API 리뷰 보고서를 작성해 주세요.

4. 결과물 예시

Codex는 대화 내역에서 아키텍처적 결론과 그 타협 근거를 아래와 같이 문헌화해 냅니다.

[결정 ID: DEC-003]
• 결정 사항: 예약 취소 이력을 Reservations 테이블에 직접 누적하지 않고 별도의 Reservation_Histories 테이블로 1:N 분리 설계.
• AS-IS (현재 설계): 예약 상태 변경이 잦아 메인 테이블의 쓰기 잠금(Write Lock) 병목 방지 및 일자별/상담사별 이력 추적 요건 충족.
• 검토 대안: Reservations 테이블에 canceled_at, cancel_reason 직접 추가 (기각: 다중 취소 이력 기록 불가 및 테이블 비대화 리스크)
• 승인 주체: PM 및 Lead Engineer (승인자: Dev_Lead)
• 향후 변경 가능성: 대규모 트래픽 발생 시 NoSQL Document DB로 이력 이관 가능성 있음.