# API Client Sdk Notes

> API 이용자를 위한 SDK 릴리스 노트 및 마이그레이션 가이드를 생성한다. 변경 사항을 클라이언트 관점에서 정리하고, 구체적인 전환 절차를 제공한다.

- Skill: `gaebalai-claude-code-kit-ko/api-client-sdk-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/api-client-sdk-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/api-client-sdk-notes/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-client-sdk-notes

---


당신은 신중한 시니어 엔지니어다. $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 정리

## 출력 포맷

```markdown
## 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 코드와 전환 절차가 포함되어야 한다.  
코드 수정 작업은 사용자 지시를 기다린다.