はじめに
API設計の方法論でも、ドキュメント自動生成でもない。「OpenAPIスペックを先に書いたら、サーバーコード・SDKドキュメント・モックサーバーが全部揃う」——実装とドキュメントのズレを根本から防ぐスペックファースト開発をClaude Codeで実現する話だ。
多くのチームはコードを先に実装してから後でOpenAPIスペックを書く「コードファースト」アプローチを取る。しかしコードが変更されるたびにスペックが古くなり、「ドキュメントが嘘をついている」状態が発生する。フロントエンドチームはスペックを信じられなくなり、毎回バックエンドに確認を取る羽目になる。
スペックファーストはこれを逆転させる。OpenAPIスペックを実装より先に書くことで、チームの合意・フロントエンドの並行開発・モックサーバーの即時提供・コントラクトテストによる自動検証が全て実現する。スペックを書くコストがネックになりがちだったが、Claude Codeがその障壁を大きく下げる。
CLAUDE.mdでOpenAPI規約を定義する——バージョン管理・スキーマ設計・エラー形式
OpenAPI規約をCLAUDE.mdで定義することが、スペックファースト設計の土台になる。Claude Codeがスペックを生成するたびに、CLAUDE.mdに書かれた規約が判断基準になる。
# CLAUDE.md（OpenAPI・スペックファースト規約）
## OpenAPI Policy
### バージョン管理
- OpenAPI 3.1.0 のみ使用（2.0/3.0は新規禁止）
- スペックファイル: openapi/paths/（パス別）+ openapi/components/（共通スキーマ）
- ルートファイル: openapi.yaml（全pathsとcomponentsをrefで参照）
### スキーマ設計ルール
- RequestとResponseの型は必ずcomponents/schemasに定義（インライン禁止）
- nullable は anyOf: [type: null] で表現（nullable: true は禁止）
- エラーレスポンスは全エンドポイントで RFC 7807 Problem Details を使用:
type, title, status, detail, instance フィールドを必須とする
### APIバージョニング
- URLパスにバージョン: /v1/、/v2/（ヘッダーバージョニング禁止）
- 破壊的変更は必ず新バージョン（v2+）で実施
- 旧バージョンのdeprecation: x-deprecated: true + sunset日付を付与
### CI/CDルール
- スペック変更のPRでは必ずopenapi-diffを実行
- breaking changesがある場合はPRにラベル[breaking-change]を付与してブロックエラーレスポンスをRFC 7807 Problem Details形式に統一する設計は特に重要だ。エンドポイントごとにエラー形式がバラバラだと、クライアント側でのエラーハンドリングが複雑になる。CLAUDE.mdに定義しておくことで、Claude Codeが生成するスペックと実装が常にRFC 7807形式に統一される。
breaking changesの自動検知をCIに組み込む設計もCLAUDE.mdで定義しておく。APIのパス削除・必須フィールド追加・型変更はフロントエンドや外部クライアントを壊す。openapi-diff（oasdiff等）をCIで実行し、breaking changesを含むPRを自動でブロックするかラベル付けを必須にする。「スペックを変えたら壊れた」という事故を防ぐ自動化ゲートになる。
Swagger UI公式リポジトリ（github.com/swagger-api/swagger-ui）自体がCLAUDE.mdを持っている。OpenAPIスペック管理の主要OSSがCLAUDE.mdで開発規約を定義しているのは、このアプローチの実用性を示す事例だ。
コードとスペックの双方向変換——既存実装からのスペック抽出とデザインファースト設計
Claude Codeのスペック生成は「既存コードからスペックを抽出する方向」と「要件からスペックを設計するデザインファースト方向」の両方に対応する。
既存コードからスペックを生成する場合の指示パターンはこうなる。
「このExpressルートファイルとTypeScript型定義を読んで。
OpenAPI 3.1スペックを生成して。
要件:
- 各エンドポイントの summary・description を詳細に
- リクエスト/レスポンスボディは全てスキーマコンポーネントに分離
- 認証（Bearer Token）とレート制限ヘッダーを含める
- エラーレスポンスはRFC 7807（Problem Details）形式」ancuta.orgのDaniel Ancutaが報告した実践例は参考になる。3,000行のモノリシックなOpenAPIファイルをClaude Codeで保守可能なモジュール構造に変換したところ、4日で完了した（手作業では数週間相当の作業量）。大規模なOpenAPIファイルを扱う場合は、ルートグループ単位（/users、/orders等）で生成してからマージするアプローチが実践的だ。30エンドポイント以上を一度に処理しようとするとコンテキストの限界に当たりやすい。
デザインファースト（要件定義からスペックを設計する）アプローチの指示パターンはこうなる。
「ユーザー管理APIのOpenAPIスペックを設計して。
エンドポイント:
- POST /users（登録・メール重複チェック）
- GET /users/{id}（権限チェック付き）
- PATCH /users/{id}（部分更新・自分のプロフィールのみ）
- DELETE /users/{id}（論理削除）
ページネーション: Cursor-based（Offset禁止）」swagger-docs-mcp（github.com/antstackio/swagger-docs-mcp）はSwaggerドキュメントをClaude Codeのコンテキストとして提供するMCPサーバーだ。これを使うと、開発者が毎回スペックを参照するのではなく、Claude Codeが常に最新のスペックを参照してコードを生成する状態になる。「このエンドポイントのPythonクライアントSDKを書いて」という指示が、スペックの型定義に完全準拠した実装として返ってくる。ただしコミュニティ製のため実際に採用する前にメンテナンス状態を確認することを推奨する。
Prism × コントラクトテスト——実装とスペックのズレを自動検知
Prism（github.com/stoplightio/prism）はStoplightが提供するOpenAPI準拠のモックサーバーで、OpenAPIスペックから即座にAPIモックサーバーを起動できる。
# OpenAPIスペックからモックサーバーを即起動
npx @stoplight/prism-cli mock openapi.yaml
# → http://localhost:4010 でモックサーバーが動作開始Claude CodeがOpenAPIスペックを生成し、Prismがそのスペックからモックサーバーを起動する。フロントエンドはバックエンド実装なしで開発を開始でき、バックエンド実装後はPrismの検証機能で「実装とスペックのズレ」を自動検知する。
フロントエンドとバックエンドの並行開発はスプリントの効率を大きく変える。スペックが決まったその日からフロントエンドが開発を始められるため、「バックエンドの実装を待っていた」という待機時間がなくなる。
コントラクトテストの生成もClaude Codeに任せられる。OpenAPIスペックを渡すと、スペックに完全準拠したテストを自動生成する（getdecipher.com）。
- 期待されるステータスコード（200/400/401/403/404等）の検証
- レスポンスボディのスキーマ準拠チェック
- 必須フィールドの存在確認
- エラーレスポンスがProblem Details形式であることの検証
GitHub ActionsにPrismを組み込むことで、PRを作成するたびにスペック準拠チェックが自動で実行される。「実装はあるがスペックと一致していない」というPRをCIでブロックできるようになる。
まとめ
CLAUDE.mdでOpenAPI規約を定義し、既存コードからのスペック抽出かデザインファーストでスペックを作り、Prismでモックサーバーを起動する。実装完了後はコントラクトテストで整合性を継続検証する——この一連のサイクルをClaude Codeが支えることで、スペックファーストが現実的なコストで回るようになる。
「single source of truth」の設計は、スペック・実装・テストが常に一致している状態を作ることだ。Claude Codeがどちら向きの変換（コード→スペック、スペック→コード）にも対応できることで、このサイクルが現実的なコストで回るようになる。
まず試すなら、既存のExpressルートファイルをClaude Codeに渡して「OpenAPI 3.1スペックを生成して」と依頼するところから始めてほしい。生成されたスペックからPrismでモックサーバーを起動するまでの体験が、スペックファーストの価値を実感する一番の近道だ。
コメント