api-client-sdk-notes

name	api-client-sdk-notes
description	API 이용자를 위한 SDK 릴리스 노트 및 마이그레이션 가이드를 생성한다. 변경 사항을 클라이언트 관점에서 정리하고, 구체적인 전환 절차를 제공한다.
argument-hint	[API 코드베이스|변경 이력|OpenAPI 명세] (선택: SDK 언어)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

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

실행 모드

• 간편 모드 (기본값): 1단계(변경 수집), 2단계(영향 분류), 5단계(릴리스 노트 작성)만 수행하고, 간결한 릴리스 노트를 반환한다.
• 상세 모드: --detailed 옵션이 포함되면, 6단계 전체를 수행하여 마이그레이션 가이드 및 체크리스트를 포함한 종합 문서를 반환한다.

$ARGUMENTS에 --detailed가 포함되지 않은 경우 간편 모드로 실행한다.
간편 모드에서는 출력 포맷 중 해당 섹션만 작성한다.

목적

API 변경 사항을 클라이언트 개발자(SDK 사용자 및 직접 API 호출 사용자) 관점에서 정리하고, 릴리스 노트 및 마이그레이션 가이드를 작성한다.
서버 내부 구현이 아니라, 사용자가 무엇을 해야 하는지에 초점을 맞춘다.
SDK가 존재하는 경우 래퍼 계층 변경까지 반영하며, 각 언어별 전환 코드 예시를 포함한다.

입력

• API 코드베이스 또는 변경 이력(git 로그, CHANGELOG 등) (필수)
• OpenAPI 명세 파일 (선택)
• SDK 코드베이스 (선택)
• 대상 언어/프레임워크 (선택: JavaScript/Python/Go/Ruby 등)
• 이전 릴리스 대비 변경 범위(태그, 커밋, 날짜 등) (선택)
• 정보가 부족하면 사용자에게 질의할 것

절차

1. 변경 사항 수집

   • Glob으로 CHANGELOG 및 릴리스 노트 관련 파일 검색
   • Grep으로 API 라우팅·컨트롤러 변경 지점 탐색
   • OpenAPI 명세가 있으면 Read로 변경된 엔드포인트 식별
   • SDK 코드가 있으면 메서드명·인자·리턴 타입 변경 수집
   • deprecated 표시 및 Sunset 헤더 설정 위치 검색

2. 클라이언트 영향 분류 수집된 변경 사항을 아래 카테고리로 분류한다:

   • Breaking Change: 클라이언트 코드 수정 필수

   • Deprecated: 현재는 동작하나 향후 제거 예정

   • New Feature: 신규 엔드포인트/파라미터

   • Improvement: 성능 개선 또는 버그 수정

   • Internal: 클라이언트 영향 없음

   • 각 변경의 영향도(High/Medium/Low) 평가

   • 변경 간 의존 관계 정리

3. 마이그레이션 절차 설계 (상세 모드 전용)

   • 각 Breaking Change에 대해:
     • Before 코드
     • After 코드
     • 변경 배경
   • SDK 사용 시 언어별 전환 예시 포함
   • 권장 적용 순서 정의
   • 예상 소요 시간 제시

4. Deprecated 항목 정리 (상세 모드 전용)

   • 대체 API 명시
   • 제거 예정 시점(Sunset)
   • 계속 사용 시 리스크 설명

5. SDK 릴리스 노트 작성

   • 시맨틱 버저닝 기준에 따른 버전 권장
   • 카테고리별 정리
   • 코드 예시 포함
   • Known Issue 및 우회 방법 명시

6. 마이그레이션 체크리스트 작성 (상세 모드 전용)

   • 전환 완료 여부 확인용 체크리스트
   • 검증 방법(테스트 절차)
   • 자주 발생하는 실수 FAQ 정리

출력 포맷

## API 릴리스 노트 / 마이그레이션 가이드

### 릴리스 정보
- **버전**: [예: v2.1.0]
- **릴리스 날짜**: [날짜]
- **이전 버전**: [예: v2.0.0]
- **시맨틱 버저닝 판정**: [Major/Minor/Patch]
- **예상 전환 소요 시간**: [예: 약 2시간]

---

### 변경 요약

| 카테고리 | 건수 | 클라이언트 대응 |
|----------|------|----------------|
| Breaking Change | X건 | 수정 필수 |
| Deprecated | X건 | 계획적 대응 |
| New Feature | X건 | 선택적 적용 |
| Improvement | X건 | 대응 불필요 |

---

### Breaking Change

#### BREAKING-001: [변경 개요]

- **영향도**: High/Medium
- **영향 엔드포인트**: [메서드 경로]
- **변경 이유**: [배경 설명]

**Before**:

[이전 코드 예시]

**After**:

[변경 후 코드 예시]

**마이그레이션 절차**:
1. [구체적 단계]
2. [구체적 단계]

#### BREAKING-002 : [변경 개요]
(이하 동일하게 반복한다)

---

### Deprecated

| 기능 | 대체 기능 | 제거 예정 | 비고 |
|------|----------|----------|------|
| [기능명] | [대체 기능] | [Sunset 날짜] | [설명] |

**전환 예시**:

// Deprecated (v2.5.0 제거 예정) [기존 코드]

// 권장 방식 [신규 코드]

---

### New Feature

#### NEW-001: [기능 요약]

- **엔드포인트**: [메서드 경로]
- **사용 목적**: [설명]

**요청 예시**:

[요청 코드]

**응답 예시**:
```json
{
  "sample": "response"
}

---

Improvement / Bug Fix

대상	내용	영향
[기능]	[개선 내용]	[클라이언트 영향]

---

마이그레이션 체크리스트

• BREAKING-001 적용 완료
• Deprecated API 사용 여부 점검
• 단위/통합 테스트 통과
• 스테이징 환경 검증 완료
• SDK 버전 업데이트 완료
• API 문서 변경 사항 검토

FAQ

*Q: [질문1] A: [답변]

*Q: [질문2] A: [답변]

Known Issues

문제	영향	임시 대응	수정 예정
[설명]	[범위]	[대응법]	[버전]

지원 정보

• 전환 지원 기간: [기간]
• 문의 채널: [Issue Tracker / 이메일]
• 관련 문서: [API 문서 URL]

## 보안 유의사항

- 릴리스 노트 작성만 수행하고 코드 변경은 하지 않는다.
- 인증 정보는 `YOUR_API_KEY` 같은 플레이스홀더를 사용한다.
- DB 구조·인프라 등 내부 구현 세부 사항은 포함하지 않는다.
- 보안 취약점의 구체적 내용은 공개 문서에 상세히 기술하지 않는다.
- Breaking Change가 존재할 경우 문서 상단에서 명확히 경고한다.

## 종료 조건

위 출력 포맷에 맞는 릴리스 노트/마이그레이션 가이드를 작성하면 종료한다.  
모든 변경 사항이 분류되어 있고, Breaking Change에는 Before/After 코드와 전환 절차가 포함되어야 한다.  
코드 수정 작업은 사용자 지시를 기다린다.