---

name: api-contract-guardian
description: CodexやClaude CodeでREST、GraphQL、RPCなどのAPIを変更する際、既存クライアントとの互換性、リクエスト・レスポンス契約、エラー形式、型定義、テストを確認するスキル。API追加・変更・リファクタリングで使う。

API Contract Guardian

目的

サーバー側の実装だけを見て変更を完了せず、既存クライアントやSDKが依存しているAPI契約を守る。

手順

1. 対象エンドポイントと、そのルート、schema、serializer、型、OpenAPI、クライアント利用箇所を特定する。
2. 変更前後で次を比較する。
   • HTTP method / path
   • 必須・任意パラメータ
   • 型・null可否・default
   • status code
   • response shape
   • error shape
3. 削除、rename、型変更、必須化など互換性を壊す変更がないか確認する。
4. 互換性を壊す必要がある場合は、段階的移行、versioning、deprecated期間を検討する。
5. API schemaと実装が一致しているか更新・検証する。
6. 正常系だけでなく、不正入力、存在しないID、権限不足など既存のエラー契約もテストする。
7. フロントエンド、SDK、CLIなどリポジトリ内の利用箇所があれば追従できているか確認する。

ルール

• 内部実装の変更と外部契約の変更を分けて考える。
• レスポンスフィールドを消す前に利用箇所を検索する。
• OpenAPIや型定義を実装と別物として放置しない。
• 互換性に不確実性がある場合は、その箇所を明示する。

完了報告

API契約の変更点、互換性の有無、更新したschema/型/テスト、残る移行事項を示す。