api-design-reviewer

API 設計レビュアー

REST API の設計を、規約、ベストプラクティス、業界標準に照らして包括的に分析・レビューします。自動リンティング、破壊的変更の検出、設計スコアカードを通じて、エンジニアリングチームによる一貫性があり、保守しやすく、適切に設計された API の構築を支援します。

主な機能

• API のリンティングと規約の分析 — リソースの命名（kebab-case の URL、camelCase のフィールド）、HTTP メソッドの使用方法、URL 構造、ステータスコードへの準拠、エラー形式の一貫性、ドキュメントの網羅性を確認します。
• 破壊的変更の検出 — 2 つの仕様バージョン間で、エンドポイントの削除、レスポンス構造の変更、フィールドの削除・名称変更、型の変更、新しい必須フィールド、ステータスコードの変更を検出し、移行ガイドを提供します。
• API 設計のスコアリング — 一貫性（30%）、ドキュメント（20%）、セキュリティ（20%）、使いやすさ（15%）、パフォーマンス（15%）に基づく加重スコアカードを作成し、A〜F の評価と推奨事項を示します。

使用するタイミング

• 新しい REST API を設計するとき、または API コントラクトをレビューするとき。
• OpenAPI/Swagger 仕様が REST の規約に準拠しているか検証するとき。
• API のバージョン管理を行い、リリース間の破壊的変更を検出するとき。
• CI で API 設計の品質を基準にデプロイを制御するとき。

まず確認すること

レビューを作成する前に、以下の情報を確認してください。不明または曖昧な項目があれば、推測せずに質問してください。

• 出力の種類 — リントレポート、設計スコアカード、破壊的変更の検出のいずれか（api_linter.py、api_scorecard.py、breaking_change_detector.py のどれを使うかが決まります）
• 仕様ファイル — OpenAPI/Swagger の JSON、または差分を取る 2 つのバージョン（ツールが解析する入力です）
• 品質基準／CI ゲート — 最低評価または破壊的変更時の失敗条件（--min-grade／--exit-on-breaking の設定、および判定の厳しさが決まります）

停止ルール：出力を最も大きく左右する 2〜3 項目だけを質問してください。ユーザーが「そのまま下書きして」と言った場合は、作業を進め、成果物の冒頭に前提を列挙してください。

ツール

ツール	目的	コマンド
api_linter.py	OpenAPI/Swagger の JSON 仕様を REST の規約とベストプラクティスに照らしてリンティングする	python scripts/api_linter.py openapi.json --format json
breaking_change_detector.py	2 つの仕様バージョン間の破壊的変更を検出する（移行ガイド付き）	python scripts/breaking_change_detector.py v1.json v2.json --exit-on-breaking
api_scorecard.py	5 つの加重評価項目に基づいて API 設計の品質を採点する（評価は A〜F）	python scripts/api_scorecard.py openapi.json --min-grade B

参考資料

タスクに合った参考資料を読み込んでください。このファイルは簡潔に保ち、必要に応じて詳細を参照します。

• references/rest-design-patterns.md — REST の命名、メソッド、URL の原則、バージョン管理戦略、ページネーションのパターン、エラー形式とステータスコード、認証／RBAC のパターン、レート制限、HATEOAS、冪等性、後方互換性のルール、OpenAPI の検証、パフォーマンスとセキュリティのベストプラクティスを説明します。エンドポイントの設計またはレビュー時に読んでください。
• references/tooling-ci-and-troubleshooting.md — 3 つのツールの機能、CI/CD と pre-commit への統合、ベストプラクティスとアンチパターンのチェックリスト、トラブルシューティング表、成功基準、CLI フラグの詳細を説明します。ツールをパイプラインに組み込むとき、またはデバッグするときに読んでください。
• references/rest_design_rules.md — REST 設計ルールの詳細なリファレンスです（リソースとアクションの違い、HTTP メソッドのセマンティクスと実例）。ルールを詳しく調べるときに読んでください。
• references/api_antipatterns.md — よくある API のアンチパターン（動詞ベースの URL／RPC の罠など）を、悪い例・良い例と推奨される修正方法とともに説明します。既存 API の設計上の問題を監査するときに読んでください。

対象範囲と制限事項

このスキルで対応すること：

• OpenAPI 3.x および Swagger 2.0 の JSON 仕様を、REST の規約に照らしてリンティングする
• 2 つの仕様バージョン間における、破壊的変更、破壊的変更の可能性がある変更、非破壊的変更を検出する
• 一貫性、ドキュメント、セキュリティ、使いやすさ、パフォーマンスの観点から API 設計の品質を評価する
• 破壊的変更が見つかった場合に、実行可能な移行ガイドを生成する

このスキルで対応しないこと：

• 実行時の API テスト、負荷テスト、コントラクトテスト（api-test-suite-builder を参照）
• GraphQL、gRPC、WebSocket の API 設計レビュー
• コードやサーバースタブからの OpenAPI 仕様の自動生成
• 認証フローの実装、OAuth サーバーの設定（engineering/ の senior-security を参照）

統合ポイント

スキル	統合内容	データフロー
engineering/api-test-suite-builder	リンターの検出結果からテストケースを生成する	リンターの問題点を、エンドポイント検証のテスト計画における優先順位に反映する
engineering/changelog-generator	リリースノートに破壊的変更を記録する	破壊的変更検出器の出力から、変更履歴向けの構造化された変更データを取得する
engineering/ci-cd-pipeline-builder	API 品質をデプロイのゲート条件にする	スコアカードの評価とリンターの終了コードを、パイプラインの品質ゲートとして統合する
engineering/senior-backend	API の実装を設計と照らしてレビューする	スコアカードの推奨事項を、バックエンドのリファクタリング方針の判断に活用する
engineering/code-reviewer	API 分析で PR レビューを充実させる	リンターと破壊的変更のレポートを、PR レビューのコメントに添付する
engineering/release-manager	バージョンの更新が変更の重大度に合っているか検証する	破壊的変更検出器の重大度レベルを、セマンティックバージョニングに基づくバージョン判断に反映する