api-versioning-plan

name	api-versioning-plan
description	API 메이저 버전 전환(v1 → v2)을 위한 단계적 마이그레이션 계획을 수립한다.
argument-hint	[API 코드베이스|OpenAPI 명세|변경 요구사항] (선택: 전환 기한)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

API 메이저 버전 업그레이드(v1 → v2)에 따른 전환 계획을 수립한다.
기존 클라이언트 영향은 최소화하면서, Breaking Change를 안전하게 도입할 수 있도록 단계적 릴리스 전략·호환성 유지 정책·클라이언트 전환 지원 전략을 설계한다.
병행 운영 기간 정책과 버전 폐기 타임라인까지 포함한 종합 전환 계획을 작성한다.

입력

• API 코드베이스 또는 OpenAPI 명세 (필수)
• v2에서 도입할 변경 요구사항 (필수)
• 전환 일정 제약 (선택)
• 현재 클라이언트 규모 및 유형 (선택)
• 기존 버저닝 방식 (선택: URL/헤더/쿼리)
• 정보가 부족하면 사용자에게 질의할 것

절차

1. 현행 구조 분석

   • 라우팅 및 컨트롤러 구조 파악
   • 현재 버저닝 방식 확인 (/v1/, 헤더, 쿼리)
   • 버전 분기 로직 및 공통 레이어 파악
   • v1 전체 엔드포인트 목록화
   • 공통 모듈(인증/직렬화/검증)의 버전 의존도 분석

2. 변경 요구사항 분류

   • 변경사항 목록화
   • Breaking / Deprecated / Additive 분류
   • 변경 간 의존성 정리
   • 우선순위 및 난이도 평가

3. 버저닝 전략 설계

   • 방식 선택:
     • URL 기반 (/api/v1/)
     • 헤더 기반 (API-Version)
     • Content Negotiation
   • 코드 공유 전략 정의
   • 분기 전략 정의 (Controller 분리 vs Adapter 계층)

4. 단계적 릴리스 전략 수립

   • Phase 0: 준비
   • Phase 1: 베타
   • Phase 2: 병행 운영
   • Phase 3: 비권장(Deprecation)
   • Phase 4: 폐기(Removal)
   • 각 단계별 기간·조건·롤백 정의

5. 클라이언트 전환 지원 설계

   • 전환 가이드 구성
   • 어댑터 계층 설계
   • Deprecation / Sunset 헤더 정책 정의
   • 공지 및 커뮤니케이션 전략
   • 사용량 모니터링 전략

6. 리스크 및 완화 전략

   • 데이터 정합성 리스크
   • 성능 리스크
   • 전환 지연 리스크
   • 롤백 시나리오 정의

출력 포맷

## API 버전 전환 계획서

### 기본 정보
- **현행 버전**: v1
- **신규 버전**: v2
- **버저닝 방식**: URL 기반(`/api/v1` → `/api/v2`)
- **병행 운영 기간**: 3~6개월 권장
- **v1 폐기 예정 시점**: YYYY-MM-DD

### 변경 목록

| # | 변경 내용 | 분류 | 우선순위 | 난이도 | 의존성 |
|---|----------|------|----------|--------|--------|
| 1 | 응답 스키마 구조 변경 | Breaking | P1 | 중 | 없음 |
| 2 | 신규 필드 추가 | Additive | P2 | 낮음 | #1 이후 |

---

### 버저닝 전략

#### 선택 방식
- **채택 방식**: URL Path Versioning
- **이유**:
  - 명확성
  - 캐시/CDN 친화적
  - 운영 및 로그 분석 용이

#### 코드 공유 전략
- 공통 비즈니스 로직은 Service Layer로 추출
- v1/v2 Controller 분리
- Serializer 계층에서 버전별 변환 처리

#### 테스트 전략
- v1/v2 독립 테스트 유지
- 공통 서비스 레벨 테스트 공유

---

### 단계별 릴리스 계획

#### Phase 0: 준비 (2주)
- 목적: v2 개발 기반 구축
- 작업:
  - [ ] 공통 로직 추출
  - [ ] v2 라우팅 구조 생성
- 완료 조건: v2 최소 기능 구현 완료
- 롤백: feature branch 유지, main 병합 금지

#### Phase 1: 베타 공개 (2~4주)
- 목적: 제한된 클라이언트 테스트
- 작업:
  - [ ] 특정 API Key에만 v2 허용
  - [ ] 피드백 수집
- 완료 조건: 주요 오류 해결
- 롤백: 트래픽 차단 후 v1 유지

#### Phase 2: 병행 운영 (3개월 권장)
- 목적: 점진적 클라이언트 전환
- 작업:
  - [ ] v1/v2 동시 운영
  - [ ] 요청 비율 모니터링
- 완료 조건: v2 사용률 90% 이상
- 롤백: 트래픽 스위치로 v1 복귀

#### Phase 3: 비권장(Deprecation)
- 헤더 설정:
  - `Deprecation: true`
  - `Sunset: YYYY-MM-DD`
- 공지 전략:
  - 이메일
  - 변경 로그
  - 대시보드 알림
- 모니터링:
  - v1 요청 비율 5% 이하 목표

#### Phase 4: 폐기(Removal)
- 폐기 조건:
  - v1 사용률 1% 미만
  - 핵심 클라이언트 전환 완료
- 폐기 후 응답:
  - `410 Gone`
  - 전환 가이드 링크 제공

### 클라이언트 전환 가이드 (개요)

#### 엔드포인트 대응표

| v1 | v2 | 변경 요약 |
|----|----|-----------|
| /api/v1/users | /api/v2/users | 응답 구조 변경 |

#### 코드 전환 예시

[v1 → v2 요청 구조 변경 예시 (문서화 예정)]

### 리스크 평가

| 리스크 | 영향도 | 발생 확률 | 완화 전략 |
|--------|--------|----------|------------|
| 데이터 정합성 불일치 | 높음 | 중 | 공통 서비스 계층 유지 |
| 병행 운영 리소스 증가 | 중 | 높음 | 오토스케일링 설정 |
| 전환 지연 | 중 | 중 | 적극적 공지 및 KPI 관리 |

### 모니터링 항목

| 지표 | 측정 방법 | 임계값 | 대응 |
|------|----------|--------|------|
| v1 요청 비율 | API Gateway 로그 | >20% | 전환 캠페인 강화 |
| v2 에러율 | APM | >2% | 롤백 검토 |
| 평균 응답시간 | 모니터링 툴 | SLA 초과 | 인프라 확장 |

안전 유의사항

• 계획 수립만 수행하며 코드 변경은 하지 않는다.
• 병행 운영 시 데이터 정합성 리스크를 반드시 통제한다.
• 즉각적인 v1 폐기는 금지한다.
• 모든 단계에 롤백 전략을 포함한다.
• Breaking Change는 단계적으로 도입한다.

종료 조건

위 형식에 따른 버전 전환 계획서를 출력하면 종료한다. 모든 변경이 분류되어 있고, 단계별 작업·완료 조건·롤백 전략이 명확히 정의되어 있어야 한다. 구현 작업은 사용자 지시를 기다린다.