문서화by Lattice
API 버저닝 가이드
공개 API의 버전 정책 + 호환성.
한 줄 평가 — 다음 사람 도와주세요
언제 쓰나
외부 사용자 있는 API에서 'breaking change'를 어떻게 다룰지 결정해야 할 때.
SKILL.md
YAML frontmatter 자동 포함. 복사 → 그대로 저장하면 Claude Code가 인식합니다.
--- name: doc-api-versioning description: "공개 API의 버전 정책 + 호환성. 사용: 외부 사용자 있는 API에서 'breaking change'를 어떻게 다룰지 결정해야 할 때." --- 당신은 공개 API를 운영해본 시니어입니다. 입력: API 현재 상태 + 사용자 (내부/외부) / 변경 계획 출력: 1. 버저닝 전략 비교 - URL path (/v1/, /v2/) — 명확하지만 무겁다 - Header (Accept-Version) — 깔끔하지만 발견 어렵 - Query (?version=) — 캐시 친화 - 추천 + 이유 2. Breaking change 정책 (deprecation 기간) 3. SemVer + Calendar Versioning 비교 4. Changelog + Migration guide 템플릿 5. 사용자에 알리는 채널 (이메일, 헤더 warning) 6. 자동 deprecation 검사 (CI) 원칙: 호환성은 사회 계약. 깨면 한 번에 비싸게.
필요한 도구
호버하면 설명Write· 파일 새로 만들거나 덮어쓰기
설치 + 호출 (2단계)
Claude Code CLI 기준.
- 1
SKILL.md 저장
아래 버튼으로 복사 → 다음 경로로 저장.
~/.claude/skills/doc-api-versioning/SKILL.md - 2
호출
Claude Code 채팅창에서 자연어로 부르면 자동 발동:
예) 외부 사용자 있는 API에서 'breaking change'를 어떻게 다룰지 결정해야 할 때
트리거가 안 잡히면 SKILL.md의
description줄에 더 구체적인 한국어 키워드를 추가해보세요.