API デザイナー

REST、GraphQL、gRPC 全般に対応したコントラクトファーストな API デザイン。OpenAPI 3.1 仕様の生成、既存 API のレビュー、後方互換性の分析、クライアントコードのスカッフォルディングを行います。

正規語彙

用語	定義
spec	API のサーフェスを記述する OpenAPI 3.1 ドキュメント（YAML または JSON）
endpoint	REST API のパス + メソッドの組み合わせ、GraphQL のクエリ/ミューテーション、gRPC の RPC
breaking change	既存クライアントがコード変更なしに動作しなくなる修正
non-breaking change	後方互換性がある修正（フィールドの追加、新しいエンドポイント、オプションパラメータなど）
resource	API を通じて公開されるドメインエンティティ（REST では名詞ベースの URL セグメント）
contract	仕様によって定義される API プロデューサーとコンシューマー間の形式的な契約
protocol	API のパラダイム：REST、GraphQL、または gRPC
surface	API が公開するエンドポイント、型、操作の完全なセット
versioning strategy	breaking change の伝達方法：URL パス、ヘッダー、またはクエリパラメータ

ディスパッチ

$ARGUMENTS	アクション
design <requirements>	要件から新しい API を設計する
spec <code or path>	既存コードから OpenAPI 3.1 仕様を生成する
review <spec or path>	既存 API 設計を監査する
version <spec or path>	バージョニングと廃止戦略
compat <old> <new>	後方互換性のdiff分析
sdk <spec or path>	クライアントコード構造をスカッフォルドする
API 設計に関する自然言語	インテントからモードを自動検出する
空	モードメニューと例を表示する

モードメニュー（引数なし）

#	モード	例
1	Design	design "User management API with RBAC"
2	Spec	spec src/routes/
3	Review	review openapi.yaml
4	Version	version openapi.yaml
5	Compat	compat v1.yaml v2.yaml
6	SDK	sdk openapi.yaml

数字を選択するか、必要なことを説明してください。

プロトコル検出

モードに入る前に入力から API プロトコルを検出します。分類により、どの規約とパターンが適用されるかが決まります。

検出シグナル：

シグナル	REST	GraphQL	gRPC
ファイル拡張子	.yaml、.json（OpenAPI）	.graphql、.gql	.proto
キーワード	endpoint、resource、CRUD、path	query、mutation、subscription、resolver	service、rpc、message、protobuf
URL パターン	/api/v1/resources	/graphql	gRPC サービス名
コードパターン	Express/FastAPI ルート、コントローラー	スキーマ定義、リゾルバー	Proto サービス定義

ルーティング：

• 1 つのプロトコルの明確なシグナル：そのプロトコルの規約を使用して進める
• 混合シグナルまたは曖昧：ユーザーに確認する —「どのプロトコル？[REST / GraphQL / gRPC]」
• プロトコルコンテキストなし（純粋な要件）：REST をデフォルトとし、仮定を注記する

検出されたプロトコルに基づいて references/rest-conventions.md、references/graphql-patterns.md、または references/grpc-patterns.md を読み込みます。

モード A：設計

要件から新しい API を設計します。references/rest-conventions.md（またはプロトコル固有のリファレンス）を読みます。

設計ステップ

1. 要件を解析する — リソース、関係、操作、認証ニーズ、制約を抽出する
2. リソースモデリング — 属性、関係、カーディナリティを持つリソースを定義する
3. エンドポイント設計 — CRUD とカスタム操作をプロトコル規約に従ったエンドポイントにマッピングする
4. リクエスト/レスポンススキーマ — 型、検証ルール、例を含むペイロードを定義する
5. 認証戦略 — ユースケースに基づいて認証アプローチ（API キー、OAuth2、JWT）を推奨する
6. エラーコントラクト — コード、メッセージ、詳細オブジェクトを持つエラーレスポンス形式を定義する
7. ページネーション＆フィルタリング — カーソルまたはオフセットページネーション、フィルタクエリパターンを適用する
8. レート制限 — エンドポイントの機密性と予想負荷に基づいて制限を推奨する
9. 仕様を生成する — 完全な OpenAPI 3.1 YAML を出力する
10. 検証する — 生成された仕様に対して scripts/api-spec-validator.py を実行する

モード B：仕様

既存コードから OpenAPI 3.1 を生成します。

仕様ステップ

1. コードベースをスキャンする — ルート定義、コントローラー、ハンドラー、デコレーターを読む
2. エンドポイントを抽出する — コードをパス + メソッド + パラメータ + レスポンス型にマッピングする
3. スキーマを推論する — 型アノテーションまたはランタイム型からリクエスト/レスポンススキーマを構築する
4. 仕様を生成する — 発見されたすべてのエンドポイントを含む OpenAPI 3.1 YAML を出力する
5. 検証する — scripts/api-spec-validator.py を実行する
6. ギャップレポート — 説明、例、またはエラーレスポンスが不足しているエンドポイントをリストする

モード C：レビュー

既存 API 設計を監査します。読み取り専用の分析です。

レビューステップ

1. 仕様を解析する — OpenAPI ドキュメントを読み込み、検証する
2. バリデーターを実行する — 構造的な問題について scripts/api-spec-validator.py を実行する
3. エンドポイントマトリックスを実行する — サーフェスの概要について scripts/api-endpoint-matrix.py を実行する
4. 規約チェック — references/rest-conventions.md に対して命名、HTTP メソッド使用法、ステータスコードを検証する
5. セキュリティ監査 — 認証カバレッジ、HTTPS 強制、機密データ公開をチェックする
6. 一貫性チェック — 命名パターン、レスポンスエンベロープ一貫性、エラー形式統一を検証する
7. レポート — 重大度別（critical、warning、info）に調査結果を表示し、具体的な修正提案を示す

モード D：バージョン

バージョニングと廃止戦略です。

バージョンステップ

1. 現在の状態を分析する — 仕様を解析し、バージョンインジケーターを特定する
2. 戦略を推奨する — URL パス対ヘッダー対クエリパラメータバージョニングを比較する（references/versioning-strategies.md を読む）
3. 廃止計画 — タイムライン、sunset ヘッダー、廃止されたエンドポイントのマイグレーションガイド
4. バージョンマトリックス — どのエンドポイントがどのバージョンに存在するかを示す表
5. マイグレーションガイドテンプレート — コンシューマーマイグレーションドキュメント用のスケルトン

モード E：互換性

2 つの仕様バージョン間の後方互換性 diff です。

互換性ステップ

1. 両方の仕様を読み込む — 古い仕様と新しい仕様の OpenAPI ドキュメントを解析する
2. 互換性チェッカーを実行する — scripts/compat-checker.py <old> <new> を実行する
3. 変更を分類する — breaking 対 non-breaking に、変更タイプと位置を含めて分類する
4. 影響評価 — どのコンシューマーが影響を受けるか、推定マイグレーション労力
5. 修復 — 各 breaking change について、後方互換性のある代替案を提案する

モード F：SDK

仕様からクライアントコード構造をスカッフォルドします。公開可能な SDK パッケージではなく、構造的な開始点です。

SDK ステップ

1. 仕様を解析する — エンドポイント、スキーマ、認証要件を抽出する
2. リソースでグループ化する — エンドポイントを論理的なクライアントモジュールに整理する
3. クライアントスケルトンを生成する — 型付けされたパラメータと戻り値の型を持つメソッドスタブ
4. 認証統合 — 認証メカニズムをクライアントコンストラクターに接続する
5. エラーハンドリング — API エラーコードをクライアント例外にマッピングする
6. 使用例 — リソースごと 1 つの例で一般的な操作を表示する

スクリプト

スクリプト	目的	実行タイミング
scripts/api-spec-validator.py	OpenAPI 3.x を完全性とベストプラクティスについて検証する	Design、Spec、Review
scripts/api-endpoint-matrix.py	仕様からエンドポイントインベントリを抽出する	Review、Version、SDK
scripts/compat-checker.py	2 つの仕様を比較して breaking change を検出する	Compat

スクリプト呼び出し

uv run python skills/api-designer/scripts/api-spec-validator.py <spec-path>
uv run python skills/api-designer/scripts/api-endpoint-matrix.py <spec-path>
uv run python skills/api-designer/scripts/compat-checker.py <old-spec> <new-spec>

すべてのスクリプトは JSON を stdout に出力し、警告を stderr に出力します。

リファレンスファイルインデックス

ファイル	コンテンツ	読むタイミング
references/rest-conventions.md	REST ベストプラクティス、HTTP メソッド、ステータスコード、命名、ページネーション、レート制限	Design、Spec、Review（REST）
references/graphql-patterns.md	GraphQL スキーマ設計、クエリパターン、エラーハンドリング、サブスクリプション	Design、Spec、Review（GraphQL）
references/grpc-patterns.md	gRPC サービスパターン、proto 設計、ストリーミング、エラーコード	Design、Spec、Review（gRPC）
references/versioning-strategies.md	URL 対ヘッダー対クエリバージョニング、廃止、後方互換性チェックリスト	Version、Compat
data/http-conventions.json	HTTP メソッドセマンティクスリファレンスデータ	Scripts
data/status-codes.json	HTTP ステータスコードガイドリファレンスデータ	Scripts

すべてのリファレンスを一度に読み込まないでください。検出されたプロトコルとアクティブなモードが必要とする内容のみを読み込みます。

重要なルール

1. モードに入る前に必ずプロトコルを検出する — 証拠なしに REST と仮定しない
2. プロトコルが曖昧な場合、ユーザーに確認する — 推測しない
3. 生成された仕様はユーザーに提示する前に api-spec-validator.py を通す必要がある
4. すべてのエンドポイントは少なくとも 1 つのエラーレスポンスを定義する必要がある（4xx または 5xx）
5. コレクションを返すリストエンドポイント向けにページネーションなしで API を設計しない
6. 互換性モードの breaking change は修復提案を含める必要がある
7. SDK モードは構造的なスカッフォルドのみを生成する — 出力がプロダクション対応であると主張しない
8. 正規語彙を一貫して使用する —「swagger」ではなく「spec」、「route」ではなく「endpoint」
9. すべての仕様は OpenAPI 3.1 を対象とする — Swagger 2.0 または OpenAPI 3.0 を生成しない
10. MCP サーバー（mcp-creator を使用）またはフロントエンド API クライアントコード向けではない

スコープ境界

対応対象：

• 要件から新しい REST、GraphQL、gRPC API を設計する
• 既存コードから OpenAPI 仕様を生成する
• API 設計をレビュー、監査する
• バージョニング戦略と廃止計画
• 仕様バージョン間の breaking change 分析
• クライアントコード構造のスカッフォルディング

対応外：

• MCP サーバー API（/mcp-creator を使用）
• フロントエンド API クライアント実装
• API ゲートウェイ設定
• ランタイム API テストまたはロードテスト
• データベーススキーマ設計（/database-architect を使用）