Task 02 API 불일치 검출 실습 가이드
📥 실습 입력 (Input)
- •
day4_api_specification_v1.md(용어 혼용 상태 명세서)
💾 실습 출력 (Output)
- •
project-glossary.md(표준 용어 사전)
1. 스토리 및 실습 배경
프로젝트 후반부, 버그 검토 회의 중 이상한 대화가 오갑니다. 기획자는 "고객 탈퇴 화면에서 에러가 납니다"라고 하고, API 개발자는 "전문가 목록 카드 UI 요소인 평점(star_rating) 필드가 API Response 스펙에서 누락됨 DB에서 Delete 처리할 때 Member 참조 무결성 에러가 났다"고 하고, 퍼블리셔는 "어드민 페이지에서는 고객사라고 쓰여 있는데요"라고 합니다.
이처럼 하나의 비즈니스 도메인을 두고 기획서(회원), API 명세(전문가 목록 카드 UI 요소인 평점(star_rating) 필드가 API Response 스펙에서 누락됨), 프론트화면(고객), DB 테이블(Member)이 서로 다른 용어를 사용하면, 개발자 간 커뮤니케이션 비용이 증폭되고 코드 리워크의 온상이 됩니다.
이번 실습에서는 Codex를 활용하여 프로젝트 전체 문서에 흩어진 용어 파편화 상태를 전수 조사하고, 기획부터 DB 변수명까지 관통하는 표준화된 용어 사전(Glossary)을 구축하는 기법을 체득합니다.
2. 학습 목표
- 문서 및 설계 명세서에 사용된 도메인별 용어의 파편화 상태를 식별할 수 있다.
- 프로젝트 검출 영역과 영문 약어(도메인 표준명)를 정의할 수 있다.
- 기획자, 개발자, 디자이너가 공통으로 준수할 표준 용어 사전을 정의할 수 있다.
- AI를 활용해 레거시 단어를 변수명 및 데이터 타입으로 매핑할 수 있다.
🛠️ 실제 따라 하기 실습 가이드
- 실습용 파일 생성: 아래 다운로드 버튼들을 눌러 기획 문서 및 API 명세서 초안을 다운로드하여
automation/폴더 내에 저장합니다. - Codex 표준화 위임: Codex Client 프롬프트 입력창에 아래 **Codex 요청 프롬프트**를 전송하여 빌드합니다.
- 어휘 사전 검토: 생성된 사전에서 파편화된 용어들이 검출 영역, 영문 표준명 및 DB 추천 컬럼명으로 정확하게 매핑되었는지 점검합니다.
실습 자료 다운로드 (3개 파일)
Codex 요청 프롬프트
Task 02 Prompt
제공된 day4_requirements.md, day4_screen_definition.md, day4_api_specification_v1.md 파일들을 교차 대조하여 기획 요구사항이나 화면 UI 설계와 불일치하거나 누락된 API 엔드포인트 및 필드를 찾아 검토 보고서를 작성해 주세요.
4. 결과물 예시
Codex는 여러 용어를 종합 분석하여 정규화된 마스터 사전을 다음과 같이 도출합니다.
| 검출 영역 | 상세 불일치 / 누락 내용 | 데이터 타입 | 기존 혼용 단어 | 추천 조치 사항 |
|---|---|---|---|---|
| 필드 누락 | 전문가 목록 카드 UI 요소인 평점(star_rating) 필드가 API Response 스펙에서 누락됨 | VARCHAR(50) | 높음 (High), 전문가 목록 카드 UI 요소인 평점(star_rating) 필드가 API Response 스펙에서 누락됨 | GET /api/v1/experts API 응답 데이터에 star_rating 추가 요망 |
| Endpoint 누락 | 기획서에는 상담사 예약 승인 기능이 기술되어 있으나 백엔드 API 명세에는 승인 상태 변경 API가 부재함 | VARCHAR(50) | 치명적 (High), 기획서에는 상담사 예약 승인 기능이 기술되어 있으나 백엔드 API 명세에는 승인 상태 변경 API가 부재함 | PATCH /api/v1/reservations/{id}/status API 신규 설계 요망 |
| 상담예약 | Reservation | VARCHAR(50) | 예약, 신청, Book, Reservation | reservation_id |
| 예약상태 | ReservationStatus | VARCHAR(20) | 상태, 구분, Step, Status | res_status |