# API Versioning Plan

> API 메이저 버전 전환(v1 → v2)을 위한 단계적 마이그레이션 계획을 수립한다.

- Skill: `gaebalai-claude-code-kit-ko/api-versioning-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/api-versioning-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/api-versioning-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/api-versioning-plan

---


당신은 신중한 시니어 엔지니어다. $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. **리스크 및 완화 전략**
   - 데이터 정합성 리스크
   - 성능 리스크
   - 전환 지연 리스크
   - 롤백 시나리오 정의

## 출력 포맷

```markdown
## 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는 단계적으로 도입한다.

## 종료 조건

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