菜单
API設計エージェント - リファクタリング後のマイクロサービスAPI設計。REST/GraphQL/gRPC/AsyncAPIの仕様書、API Gateway設計、認証・認可設計を策定。/design-api [対象パス] で呼び出し。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/majiayu000/claude-skill-registry --skill design-api命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
LLM token logprobs and calibration. Per-decision confidence, ECE, Brier, reliability diagrams, low-confidence triage.
Analyze LLM token logprobs and calibration. Use for per-decision confidence, ECE, Brier scores, reliability diagrams, and low-confidence triage.
回顾最近 N 天的 Claude Code 使用记录——扫描原始会话数据，按主题分组汇总"我都做了什么"，并从个人操作系统视角输出模式、风险与增删建议。当用户说 /recap、"看看我这几天做了什么"、"回顾一下我最近的会话"、"这两天我用 claude 干了啥"、"活动回顾" 时使用。
基于 SOC 职业分类
正在显示 SKILL.md
| name | design-api |
| description | API設計エージェント - リファクタリング後のマイクロサービスAPI設計。REST/GraphQL/gRPC/AsyncAPIの仕様書、API Gateway設計、認証・認可設計を策定。/design-api [対象パス] で呼び出し。 |
| user_invocable | true |
リファクタリング後のマイクロサービスAPIを設計するエージェントです。
このエージェントは、マイクロサービス設計の結果をもとに、以下を策定します：
以下の中間ファイルが存在すること：
01_analysis/ 配下の分析結果03_design/target-architecture.md03_design/scalardb-schema.md（存在する場合）設計結果は reports/03_design/ に出力します。
重要: 各ステップ完了時に即座にファイルを出力してください。
reports/03_design/
├── api-design-overview.md # API設計概要
├── api-specifications/ # API仕様書ディレクトリ
│ ├── openapi/ # OpenAPI (REST) 仕様
│ │ └── [service]-api.yaml
│ ├── graphql/ # GraphQL スキーマ
│ │ └── [service]-schema.graphql
│ ├── grpc/ # gRPC プロトコル定義
│ │ └── [service].proto
│ └── asyncapi/ # AsyncAPI (イベント) 仕様
│ └── [service]-events.yaml
├── api-gateway-design.md # API Gateway設計
└── api-security-design.md # 認証・認可設計
あなたはAPI設計の専門家です。以下の手順で設計を実行してください。
API設計の基本原則：
| 原則 | 説明 |
|---|---|
| Contract First | 実装前にAPI仕様を定義 |
| Consumer Driven | 利用者のニーズを優先 |
| Consistency | 命名規則、エラー形式の統一 |
| Versioning | 後方互換性を保つバージョン管理 |
| Security by Design | セキュリティを最初から考慮 |
| Documentation | 常に最新のドキュメント |
| Observability | トレーシング、ログ、メトリクス |
各サービス・ユースケースに適した通信パターンを選定：
## API通信パターン選定
### サービス別API方式
| サービス | 外部API | 内部API | イベント | 選定理由 |
|---------|--------|--------|---------|---------|
| Order Service | REST | gRPC | Kafka | CRUDメイン、高性能内部通信 |
| Product Service | GraphQL | gRPC | - | 柔軟なクエリ要件 |
| Notification Service | - | gRPC | Kafka | イベント駆動 |
### 通信パターン判断基準
| パターン | 適用条件 | メリット | デメリット |
|---------|---------|---------|----------|
| REST | CRUD操作、外部公開 | 標準的、ツール豊富 | オーバーフェッチ |
| GraphQL | 複雑なクエリ、BFF | 柔軟、効率的 | 学習コスト |
| gRPC | 内部通信、高性能 | 高速、型安全 | ブラウザ非対応 |
| AsyncAPI | イベント駆動 | 疎結合、スケーラブル | 複雑性 |
# URL設計規則
paths:
# リソース（複数形）
/orders:
get: 注文一覧取得
post: 注文作成
/orders/{orderId}:
get: 注文詳細取得
put: 注文更新
delete: 注文削除
# サブリソース
/orders/{orderId}/items:
get: 注文明細一覧
post: 注文明細追加
# アクション（動詞が必要な場合）
/orders/{orderId}/actions/cancel:
post: 注文キャンセル
openapi: 3.1.0
info:
title: "[Service Name] API"
version: "1.0.0"
description: |
[サービスの説明]
contact:
name: API Support
email: api-support@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://api-staging.example.com/v1
description: Staging
tags:
- name: orders
description: 注文関連API
paths:
/orders:
get:
summary: 注文一覧取得
operationId: listOrders
tags: [orders]
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageToken'
- name: status
in: query
schema:
[]
[]
[, , , ]
[, , , , ]
[, ]
## エラーレスポンス標準
### HTTPステータスコード
| コード | 意味 | 使用場面 |
|-------|-----|---------|
| 400 | Bad Request | バリデーションエラー |
| 401 | Unauthorized | 認証エラー |
| 403 | Forbidden | 認可エラー |
| 404 | Not Found | リソース不在 |
| 409 | Conflict | 競合（楽観ロック失敗等） |
| 422 | Unprocessable Entity | ビジネスルール違反 |
| 429 | Too Many Requests | レート制限超過 |
| 500 | Internal Server Error | サーバーエラー |
| 503 | Service Unavailable | サービス一時停止 |
### エラーレスポンス形式
```json
{
"code": "ORDER_ALREADY_CANCELLED",
"message": "注文は既にキャンセルされています",
"details": [
{
"field": "orderId",
"reason": "Order with id '123' is already in CANCELLED status"
}
],
"traceId": "abc123xyz",
"timestamp": "2024-01-15T10:30:00Z"
}
### Step 4: GraphQL設計
#### 4.1 スキーマ設計
```graphql
# schema.graphql
"""
注文サービス GraphQL スキーマ
"""
type Query {
"""注文を取得"""
order(id: ID!): Order
"""注文一覧を取得"""
orders(
filter: OrderFilter
pagination: PaginationInput
): OrderConnection!
"""顧客の注文を取得"""
ordersByCustomer(customerId: ID!): [Order!]!
}
type Mutation {
"""注文を作成"""
createOrder(input: CreateOrderInput!): CreateOrderPayload!
"""注文をキャンセル"""
cancelOrder(input: CancelOrderInput!): CancelOrderPayload!
"""注文ステータスを更新"""
updateOrderStatus(input: UpdateOrderStatusInput!): UpdateOrderStatusPayload!
}
type Subscription {
"""注文ステータス変更を購読"""
orderStatusChanged(orderId: ID!): OrderStatusChangedEvent!
}
# Types
type Order implements Node {
id: ID!
customer: Customer!
status: OrderStatus!
items: [OrderItem!]!
totalAmount: Money!
createdAt: DateTime!
updatedAt: DateTime!
}
type OrderItem {
id: ID!
product: Product!
quantity: Int!
unitPrice: Money!
subtotal: Money!
}
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type OrderEdge {
node: Order!
cursor: String!
}
enum OrderStatus {
PENDING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
}
# Inputs
input CreateOrderInput {
customerId: ID!
items: [OrderItemInput!]!
shippingAddress: AddressInput!
}
input OrderItemInput {
productId: ID!
quantity: Int!
}
input OrderFilter {
status: [OrderStatus!]
customerId: ID
createdAfter: DateTime
createdBefore: DateTime
}
# Payloads
type CreateOrderPayload {
order: Order
errors: [UserError!]!
}
type UserError {
field: [String!]
message: String!
code: String!
}
# Scalars
scalar DateTime
scalar Money
## GraphQL設計原則
### 命名規則
- Query: `order`, `orders`, `ordersByCustomer`（名詞）
- Mutation: `createOrder`, `updateOrder`, `cancelOrder`（動詞+名詞）
- Subscription: `orderStatusChanged`（過去分詞+Event）
### ペイロードパターン
- Mutation結果は専用Payloadタイプを返す
- errorsフィールドでユーザー向けエラーを返す
- 成功時もエラー時も同じ型で返す
### ページネーション
- Relay Connection仕様に準拠
- edges, pageInfo, totalCountを含む
### N+1問題対策
- DataLoaderパターンを使用
- @defer, @streamディレクティブの活用
// order_service.proto
syntax = "proto3";
package order.v1;
option java_multiple_files = true;
option java_package = "com.example.order.v1";
option go_package = "github.com/example/order/v1;orderv1";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
// 注文サービス
service OrderService {
// 注文を作成
rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
// 注文を取得
rpc GetOrder(GetOrderRequest) returns (Order);
// 注文一覧を取得
rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
// 注文をキャンセル
rpc CancelOrder(CancelOrderRequest) returns (Order);
// 注文ステータスをストリーミング
rpc WatchOrderStatus(WatchOrderStatusRequest) returns (stream OrderStatusEvent);
}
// メッセージ定義
message Order {
string id = 1;
string customer_id = 2;
OrderStatus status = 3;
repeated OrderItem items = 4;
int64 total_amount = 5; // 金額は最小単位（円）
google.protobuf.Timestamp created_at = 6;
google.protobuf.Timestamp updated_at = 7;
}
message OrderItem {
string id = 1;
string product_id = 2;
int32 quantity = 3;
int64 unit_price = 4;
}
enum OrderStatus {
ORDER_STATUS_UNSPECIFIED = 0;
ORDER_STATUS_PENDING = 1;
ORDER_STATUS_CONFIRMED = 2;
ORDER_STATUS_SHIPPED = 3;
ORDER_STATUS_DELIVERED = 4;
ORDER_STATUS_CANCELLED = 5;
}
// リクエスト/レスポンス
message CreateOrderRequest {
string customer_id = 1;
repeated CreateOrderItem items = 2;
Address shipping_address = 3;
}
message CreateOrderItem {
string product_id = 1;
int32 quantity = 2;
}
message CreateOrderResponse {
Order order = 1;
}
message GetOrderRequest {
string id = 1;
}
message ListOrdersRequest {
int32 page_size = 1;
string page_token = 2;
OrderFilter filter = 3;
}
message OrderFilter {
repeated OrderStatus statuses = 1;
string customer_id = 2;
}
message ListOrdersResponse {
repeated Order orders = 1;
string next_page_token = 2;
int32 total_count = 3;
}
message CancelOrderRequest {
string id = 1;
string reason = 2;
}
message WatchOrderStatusRequest {
string order_id = 1;
}
message OrderStatusEvent {
string order_id = 1;
OrderStatus previous_status = 2;
OrderStatus current_status = 3;
google.protobuf.Timestamp changed_at = 4;
}
message Address {
string postal_code = 1;
string prefecture = 2;
string city = 3;
string street = 4;
string building = 5;
}
## gRPC設計原則
### バージョニング
- パッケージ名にバージョンを含める: `order.v1`
- 破壊的変更時は新バージョン作成: `order.v2`
### フィールド番号
- 1-15: 頻繁に使用するフィールド（1バイト）
- 16以降: それ以外のフィールド
- 削除したフィールド番号は再利用しない
### エラーハンドリング
- google.rpc.Statusを使用
- 詳細エラーはdetailsフィールドで返す
### ストリーミング
- Server Streaming: 大量データ、リアルタイム更新
- Client Streaming: バッチ処理
- Bidirectional: チャット、リアルタイム同期
# order-events.asyncapi.yaml
asyncapi: 3.0.0
info:
title: Order Events API
version: 1.0.0
description: 注文サービスが発行するイベント
servers:
production:
host: kafka.example.com:9092
protocol: kafka
description: Production Kafka
channels:
order.created:
address: order.created
messages:
orderCreated:
$ref: '#/components/messages/OrderCreated'
order.status.changed:
address: order.status.changed
messages:
orderStatusChanged:
$ref: '#/components/messages/OrderStatusChanged'
order.cancelled:
address: order.cancelled
messages:
orderCancelled:
$ref: '#/components/messages/OrderCancelled'
operations:
publishOrderCreated:
action: send
channel:
$ref: '#/channels/order.created'
[, , , ]
[, , , ]
[, , ]
[, ]
[, , , , ]
このステップ完了時に出力: reports/03_design/api-gateway-design.md
## API Gateway設計
### アーキテクチャ
```mermaid
graph TB
subgraph External["外部"]
Web[Web Client]
Mobile[Mobile App]
Partner[Partner System]
end
subgraph Gateway["API Gateway Layer"]
Kong[Kong Gateway]
subgraph Plugins
Auth[認証プラグイン]
RateLimit[レート制限]
Transform[変換]
Logging[ログ]
end
end
subgraph Internal["内部サービス"]
BFF[BFF Service]
Order[Order Service]
Product[Product Service]
User[User Service]
end
Web --> Kong
Mobile --> Kong
Partner --> Kong
Kong --> BFF
Kong --> Order
Kong --> Product
Kong --> User
| パス | バックエンド | 認証 | レート制限 |
|---|---|---|---|
/api/v1/orders/* | Order Service | JWT | 100 req/min |
/api/v1/products/* | Product Service | API Key | 1000 req/min |
/api/v1/users/* | User Service | JWT | 50 req/min |
/graphql | BFF Service | JWT | 200 req/min |
/partner/v1/* | Partner API | mTLS | 500 req/min |
# kong.yml
_format_version: "3.0"
services:
- name: order-service
url: http://order-service:8080
routes:
- name: order-route
paths:
- /api/v1/orders
strip_path: false
plugins:
- name: jwt
- name: rate-limiting
config:
minute: 100
policy: local
- name: correlation-id
config:
header_name: X-Correlation-ID
generator: uuid
- name: graphql-service
url: http://bff-service:8080
routes:
- name: graphql-route
paths:
- /graphql
methods:
- POST
plugins:
-
| クライアント種別 | 制限 | 超過時の対応 |
|---|---|---|
| 一般ユーザー | 100 req/min | 429 + Retry-After |
| プレミアムユーザー | 500 req/min | 429 + Retry-After |
| パートナー | 1000 req/min | 429 + 担当者通知 |
| 内部サービス | 制限なし | - |
### Step 8: 認証・認可設計
**このステップ完了時に出力**: `reports/03_design/api-security-design.md`
```markdown
## 認証・認可設計
### 認証方式
| 方式 | 用途 | 実装 |
|-----|-----|-----|
| JWT (OAuth2) | ユーザー認証 | Keycloak |
| API Key | パートナー認証 | Kong |
| mTLS | サービス間認証 | Istio |
| Service Account | 内部バッチ | Kubernetes SA |
### OAuth2フロー
```mermaid
sequenceDiagram
participant User
participant WebApp
participant Gateway as API Gateway
participant Keycloak
participant Service
User->>WebApp: ログイン要求
WebApp->>Keycloak: 認可コードフロー開始
Keycloak->>User: ログイン画面
User->>Keycloak: 認証情報入力
Keycloak->>WebApp: 認可コード
WebApp->>Keycloak: トークン要求
Keycloak->>WebApp: Access Token + Refresh Token
WebApp->>Gateway: API要求 + Bearer Token
Gateway->>Gateway: JWT検証
Gateway->>Service: 要求転送 + クレーム
Service->>Gateway: レスポンス
Gateway->>WebApp: レスポンス
{
"sub": "user-123",
"iss": "https://auth.example.com",
"aud": ["order-service", "product-service"],
"exp": 1704067200,
"iat": 1704063600,
"roles": ["customer", "premium"],
"permissions": ["orders:read", "orders:create"],
"tenant_id": "tenant-abc",
"metadata": {
"customer_tier": "gold"
}
}
| ロール | 権限 | 説明 |
|---|---|---|
| admin | *:* | 全権限 |
| operator | orders:*, products:read | 運用担当 |
| customer | orders:read:own, orders:create | 一般顧客 |
| partner | orders:read, products:read | パートナー |
| viewer | *:read | 閲覧のみ |
scopes:
orders:read: 注文の参照
orders:create: 注文の作成
orders:update: 注文の更新
orders:delete: 注文の削除
orders:read:own: 自分の注文のみ参照
products:read: 商品の参照
products:write: 商品の作成・更新
users:read: ユーザー情報の参照
users:write: ユーザー情報の更新
### Step 9: API バージョニング戦略
```markdown
## APIバージョニング戦略
### バージョニング方式
| 方式 | 例 | 採用 |
|-----|---|-----|
| URLパス | `/api/v1/orders` | ✅ 推奨 |
| クエリパラメータ | `?version=1` | - |
| ヘッダー | `Accept-Version: v1` | - |
| Accept | `Accept: application/vnd.example.v1+json` | - |
### 採用方式: URLパスバージョニング
**理由:**
- 明示的で分かりやすい
- キャッシュしやすい
- ドキュメント化しやすい
- API Gatewayでルーティングしやすい
### バージョン管理ルール
| ルール | 説明 |
|-------|------|
| メジャーバージョン | 破壊的変更時にインクリメント（v1 → v2） |
| 後方互換性 | フィールド追加は同一バージョン内で可 |
| 非推奨期間 | 旧バージョンは最低6ヶ月間サポート |
| サンセット | Sunset ヘッダーで廃止日を通知 |
### 非推奨通知
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jul 2025 00:00:00 GMT
Link: </api/v2/orders>; rel="successor-version"
### Step 10: API設計概要の出力
**最終出力**: `reports/03_design/api-design-overview.md`
### Step 11: Mermaid図の検証
出力したファイルのMermaid図を検証し、エラーがあれば修正：
```bash
# 出力ファイルのMermaid検証
/fix-mermaid ./reports/03_design
検証項目:
subgraph "API Gateway Layer"）## API設計概要
### サービス別API一覧
| サービス | REST | GraphQL | gRPC | Events | 仕様書 |
|---------|------|---------|------|--------|-------|
| Order Service | ✅ | - | ✅ | ✅ | [OpenAPI](./api-specifications/openapi/order-api.yaml) |
| Product Service | ✅ | ✅ | ✅ | - | [GraphQL](./api-specifications/graphql/product-schema.graphql) |
| User Service | ✅ | - | ✅ | ✅ | [OpenAPI](./api-specifications/openapi/user-api.yaml) |
| Notification Service | - | - | ✅ | ✅ | [AsyncAPI](./api-specifications/asyncapi/notification-events.yaml) |
### エンドポイント総覧
| エンドポイント | メソッド | サービス | 認証 | 説明 |
|--------------|--------|---------|-----|------|
| `/api/v1/orders` | GET | Order | JWT | 注文一覧 |
| `/api/v1/orders` | POST | Order | JWT | 注文作成 |
| `/api/v1/orders/{id}` | GET | Order | JWT | 注文詳細 |
| `/api/v1/products` | GET | Product | API Key | 商品一覧 |
| `/graphql` | POST | BFF | JWT | GraphQLエンドポイント |
### 共通仕様
- 認証: OAuth2 (JWT)
- エラー形式: RFC 7807 Problem Details
- ページネーション: Cursor-based
- 日時形式: ISO 8601 (UTC)
- 言語: Accept-Languageヘッダーで切り替え
API設計概要（設計原則、サービス別API一覧、エンドポイント総覧、共通仕様）
各サービスのAPI仕様書（OpenAPI、GraphQL、gRPC、AsyncAPI）
API Gateway設計（アーキテクチャ、ルーティング、レート制限、Kong設定）
認証・認可設計（認証方式、OAuth2フロー、JWT設計、RBAC）
# 既存APIの抽出
mcp__serena__find_symbol で Controller/Handler クラスを検索
mcp__serena__get_symbols_overview でエンドポイント一覧を取得
# OpenAPI検証
npx @stoplight/spectral-cli lint openapi.yaml
# GraphQLスキーマ検証
npx graphql-inspector validate schema.graphql
# AsyncAPI検証
npx @asyncapi/cli validate asyncapi.yaml
# OpenAPI → HTML
npx @redocly/cli build-docs openapi.yaml
# GraphQL → ドキュメント
npx graphql-markdown schema.graphql
# AsyncAPI → HTML
npx @asyncapi/cli generate fromTemplate asyncapi.yaml @asyncapi/html-template
| アンチパターン | 問題 | 推奨 |
|---|---|---|
| 動詞URL | /getOrders, /createOrder | リソース名 + HTTPメソッド |
| ネストが深いURL | /users/1/orders/2/items/3 | 最大2階層まで |
| バージョンなし | 破壊的変更時に問題 | URLパスでバージョン管理 |
| 曖昧なエラー | {"error": "failed"} | 構造化エラーレスポンス |
| 認証情報をURLに | ?token=xxx | Authorizationヘッダー |