api-versioning
APIバージョニング戦略と後方互換性管理を専門とするスキル。破壊的変更の管理、段階的廃止プロセス、バージョン間の移行ガイド作成を支援します。**Anchors(参考資料):**• 『RESTful Web APIs』(Leonard Richardson)/ 適用: API設計とバージョニング戦略 / 目的: RESTfulなバージョニング方式の理解と実装**Triggers(自動発動条件):**- API バージョニング戦略を決定する時- 破壊的変更を導入する時- エンドポイントを非推奨化する時- バージョン間の移行ガイドを作成する時- APIバージョン管理を設計する時- 後方互換性を検証する時
name: api-versioning description: | APIバージョニング戦略と後方互換性管理を専門とするスキル。破壊的変更の管理、段階的廃止プロセス、バージョン間の移行ガイド作成を支援します。
Anchors(参考資料): • 『RESTful Web APIs』(Leonard Richardson)/ 適用: API設計とバージョニング戦略 / 目的: RESTfulなバージョニング方式の理解と実装
Triggers(自動発動条件): - API バージョニング戦略を決定する時 - 破壊的変更を導入する時 - エンドポイントを非推奨化する時 - バージョン間の移行ガイドを作成する時 - APIバージョン管理を設計する時 - 後方互換性を検証する時 allowed-tools: - Read - Write - Edit - Bash - Glob - Grep
APIバージョニング
概要
APIバージョニング戦略と後方互換性管理を専門とするスキル。破壊的変更の定義と管理、段階的廃止(Deprecation)プロセス、バージョン間の移行ガイド作成を支援します。
対応範囲:
- APIバージョニング方式の選択(URI、ヘッダー、クエリパラメータなど)
- 破壊的変更の検出と影響分析
- エンドポイント廃止の段階的実行
- 後方互換性の維持戦略
- バージョン間の移行ガイド自動生成
詳細な手順や背景は references/Level1_basics.md、references/Level2_intermediate.md 以上を参照してください。
ワークフロー
Phase 1: 目的と前提の整理
目的: タスクの目的と前提条件を明確にする
アクション:
references/Level1_basics.mdとreferences/Level2_intermediate.mdを確認- 必要な references/scripts/templates を特定
Task: agents/analyze-versioning-context.md を参照
Phase 2: スキル適用
目的: スキルの指針に従って具体的な作業を進める
アクション:
- 関連リソースやテンプレートを参照しながら作業を実施
- 重要な判断点をメモとして残す
Task: agents/design-versioning-strategy.md を参照
Phase 3: 検証と記録
目的: 成果物の検証と実行記録の保存
アクション:
scripts/validate-skill.mjsでスキル構造を確認- 成果物が目的に合致するか確認
scripts/log_usage.mjsを実行して記録を残す
Task: agents/validate-versioning.md を参照
Task仕様ナビ
| Task | 説明 | リソース | スクリプト |
|---|---|---|---|
| バージョニング方式の決定 | URI/ヘッダー/クエリなどの方式選択 | versioning-strategies.md |
- |
| 破壊的変更の検出 | APIの変更が破壊的かを判定 | breaking-changes.md |
check-breaking-changes.js |
| 廃止プロセス実行 | エンドポイント段階的廃止 | deprecation-process.md |
generate-migration-guide.sh |
| 移行ガイド作成 | バージョン間の移行手順書 | migration-guide-template.md |
generate-migration-guide.sh |
| 非推奨通知 | クライアントへの廃止予告 | deprecation-notice-template.md |
- |
| 後方互換性検証 | 変更が互換性を保つか確認 | Level2_intermediate.md |
- |
ベストプラクティス
すべきこと
- バージョニング戦略を決定する時:
versioning-strategies.mdで各方式の利点と制限を確認 - 破壊的変更を導入する時:
check-breaking-changes.jsで事前検出 - エンドポイントを非推奨化する時:
deprecation-process.mdに基づいて段階的廃止を計画 - バージョン間の移行ガイドを作成する時:
migration-guide-template.mdを活用 - 後方互換性を維持する時:
Level3_advanced.mdの互換性パターンを参考 - 複雑な変更を行う時: 複数の関連リソースを参照して総合的に判断
避けるべきこと
- 予期せぬ破壊的変更を導入することを避ける
- 廃止予告なしにエンドポイント削除を避ける
- アンチパターンや注意点を確認せずに進めることを避ける
- 後方互換性オプションを検討せずに決定することを避ける
- ドキュメント作成なしにバージョン変更を進めることを避ける
リソース参照
学習用ドキュメント
| リソース | 説明 |
|---|---|
references/Level1_basics.md |
レベル1: バージョニング基礎概念 |
references/Level2_intermediate.md |
レベル2: 実務的なバージョニング運用 |
references/Level3_advanced.md |
レベル3: 複雑なバージョニング設計 |
references/Level4_expert.md |
レベル4: エンタープライズ対応戦略 |
テクニカルリソース
| リソース | 用途 |
|---|---|
references/breaking-changes.md |
破壊的変更の定義と検出方法 |
references/deprecation-process.md |
段階的廃止プロセスとHTTPヘッダー |
references/versioning-strategies.md |
バージョニング方式の比較 |
references/requirements-index.md |
要求仕様の索引 |
テンプレート
| テンプレート | 用途 |
|---|---|
assets/deprecation-notice-template.md |
廃止予告メッセージ作成 |
assets/migration-guide-template.md |
バージョン間移行ガイド作成 |
ユーティリティスクリプト
| スクリプト | 機能 |
|---|---|
scripts/check-breaking-changes.js |
破壊的変更の自動検出 |
scripts/generate-migration-guide.sh |
移行ガイドの自動生成 |
scripts/validate-skill.mjs |
スキル構造の検証 |
scripts/log_usage.mjs |
使用記録と自動評価 |
参考書籍
- 『RESTful Web APIs』(Leonard Richardson)- リソース設計とAPI設計原則
変更履歴
| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2025-12-31 | agents/3ファイル追加、Phase別Task参照を追加、name修正 |
| 1.0.0 | 2025-12-31 | 18-skills.md仕様対応:YAML frontmatter更新、Triggers追加、Task仕様ナビテーブル追加 |