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 등)
이전 릴리스 대비 변경 범위(태그, 커밋, 날짜 등) (선택)
정보가 부족하면 사용자에게 질의할 것

절차

변경 사항 수집
- Glob으로 CHANGELOG 및 릴리스 노트 관련 파일 검색
- Grep으로 API 라우팅·컨트롤러 변경 지점 탐색
- OpenAPI 명세가 있으면 Read로 변경된 엔드포인트 식별
- SDK 코드가 있으면 메서드명·인자·리턴 타입 변경 수집
- deprecated 표시 및 Sunset 헤더 설정 위치 검색
클라이언트 영향 분류 수집된 변경 사항을 아래 카테고리로 분류한다:
- Breaking Change: 클라이언트 코드 수정 필수
- Deprecated: 현재는 동작하나 향후 제거 예정
- New Feature: 신규 엔드포인트/파라미터
- Improvement: 성능 개선 또는 버그 수정
- Internal: 클라이언트 영향 없음
- 각 변경의 영향도(High/Medium/Low) 평가
- 변경 간 의존 관계 정리
마이그레이션 절차 설계 (상세 모드 전용)
- 각 Breaking Change에 대해:
  - Before 코드
  - After 코드
  - 변경 배경
- SDK 사용 시 언어별 전환 예시 포함
- 권장 적용 순서 정의
- 예상 소요 시간 제시
Deprecated 항목 정리 (상세 모드 전용)
- 대체 API 명시
- 제거 예정 시점(Sunset)
- 계속 사용 시 리스크 설명
SDK 릴리스 노트 작성
- 시맨틱 버저닝 기준에 따른 버전 권장
- 카테고리별 정리
- 코드 예시 포함
- Known Issue 및 우회 방법 명시
마이그레이션 체크리스트 작성 (상세 모드 전용)
- 전환 완료 여부 확인용 체크리스트
- 검증 방법(테스트 절차)
- 자주 발생하는 실수 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 코드와 전환 절차가 포함되어야 한다.  
코드 수정 작업은 사용자 지시를 기다린다.

Más de este repositorio

mismo repositorio

api-auth-review

gaebalai/claude-code-kit-ko

API 인증/인가(Authorization) 설계를 리뷰하고, 권한 체크 누락·스코프 설계 미흡·권한 상승 리스크를 탐지한다. 접근 통제의 안전성을 검증한다.

2026-02-252

api-endpoint-design

gaebalai/claude-code-kit-ko

요구사항으로부터 RESTful API 엔드포인트를 설계한다. 네이밍 규칙, 리소스 단위, 에러 처리, 응답 구조를 일관되게 정의한다.

2026-02-252

api-error-contract

gaebalai/claude-code-kit-ko

API 에러 코드 체계와 에러 응답 계약(Contract)을 설계한다. 일관된 에러 핸들링 규칙을 정의한다.

2026-02-252

api-openapi-diff

gaebalai/claude-code-kit-ko

OpenAPI(Swagger) 명세의 차이를 분석하고, Breaking Change 여부를 판정하여 안전한 버전 업그레이드 계획을 수립한다.

2026-02-252

api-pagination-standard

gaebalai/claude-code-kit-ko

API 리스트 엔드포인트의 페이지네이션·필터링·정렬 구현을 분석하고, 통일된 표준 규격을 수립한다.

2026-02-252

api-versioning-plan

gaebalai/claude-code-kit-ko

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

2026-02-252

## 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**:

**마이그레이션 절차**: 1. [구체적 단계] 2. [구체적 단계] #### BREAKING-002 : [변경 개요] (이하 동일하게 반복한다) --- ### Deprecated | 기능 | 대체 기능 | 제거 예정 | 비고 | |------|----------|----------|------| | [기능명] | [대체 기능] | [Sunset 날짜] | [설명] | **전환 예시**:

대상

내용

영향

[기능]

[개선 내용]

[클라이언트 영향]

문제

영향

임시 대응

수정 예정

[설명]

[범위]

[대응법]

[버전]

## 보안 유의사항 - 릴리스 노트 작성만 수행하고 코드 변경은 하지 않는다. - 인증 정보는 `YOUR_API_KEY` 같은 플레이스홀더를 사용한다. - DB 구조·인프라 등 내부 구현 세부 사항은 포함하지 않는다. - 보안 취약점의 구체적 내용은 공개 문서에 상세히 기술하지 않는다. - Breaking Change가 존재할 경우 문서 상단에서 명확히 경고한다. ## 종료 조건 위 출력 포맷에 맞는 릴리스 노트/마이그레이션 가이드를 작성하면 종료한다. 모든 변경 사항이 분류되어 있고, Breaking Change에는 Before/After 코드와 전환 절차가 포함되어야 한다. 코드 수정 작업은 사용자 지시를 기다린다.