はじめに
多くのチームで同じことが起きている。
Day 1にOpenAPI仕様書を書く。Day 7に仕様変更が入り、仕様書の更新を忘れる。Day 30で仕様書と実装が乖離している。Day 60になると誰も仕様書を信用しなくなる——。
この「仕様書が死ぬ」問題は、APIドキュメントを「実装の後に書くもの」として扱うことから生まれる。対処療法としてドキュメントを書いても、次の変更で同じ問題が繰り返される。
解決策は「仕様が先、コードが後」というアプローチの転換だ。Heeki Park（AWS）は2026年3月、このスペックドリブン開発（SDD）とClaude Codeを組み合わせた実践報告でこう述べている。「SQLite→IndexedDB移行を手動で2〜3日かかる作業を、この手法で半日で完了し、しかも品質が高かった」。
この記事では、Claude Code × OpenAPI 3.1によるスペックドリブン開発の全体像を解説する。
スペックドリブン開発とClaude Codeの相性
コードファーストとスペックファーストの違いはシンプルだ。
| アプローチ | フロー | 問題点 |
|---|---|---|
| コードファースト | 実装→後付けドキュメント | 仕様書がすぐに古くなる |
| スペックファースト（SDD） | 仕様設計→仕様書を元にコード生成 | 仕様書が常に最新状態 |
Claude Codeとの相性が特に良い理由は、仕様書（YAML/JSON）を読み込んで実装コード・テスト・型定義を一括生成できるからだ。仕様が変わったら仕様書を修正して再生成するだけで、実装とのズレが発生しない構造になる。
Claude Code × OpenAPI 3.1 実践ワークフロー
基本フローはシンプルだ。
1. OpenAPI仕様書を設計（Claude Codeが支援）
↓
2. 仕様書をソースオブトゥルースとして保存
↓
3. Claude Codeが仕様書からコード生成
↓
4. テスト・バリデーション
↓
5. 仕様変更時は仕様書を先に更新→コード再生成
Step 1: Claude Codeに仕様設計を依頼する
コードを書く前に仕様設計だけを依頼するのがポイントだ。
この機能のOpenAPI 3.1仕様書を設計して（コードはまだ書かない）：
- ユーザー管理API（CRUD）
- 認証: JWT Bearer Token
- ページネーション: cursor-based
- エラーレスポンス形式: { error: string, code: string, details: object }
- OpenAPI 3.1 YAML形式で出力して
Claude Codeは仕様書を生成し、エラーレスポンスを $ref でコンポーネント化する等のベストプラクティスも自然に適用する。
Step 2: 仕様書からコード・型定義・テストを生成
openapi.yamlを元に以下を生成して：
1. TypeScriptの型定義（src/types/api.ts）
2. Express.jsのルーターとコントローラー
3. Zodによるリクエストバリデーション
4. ユニットテスト（全エンドポイント）
仕様書と実装を常に同期させること
Step 3: ルールファイルで仕様ドリフトを防ぐ
.claude/rules/api-design.md にルールを配置すると、src/routes/** や openapi.yaml を扱う際に自動ロードされる。
---
paths:
- "src/routes/**"
- "openapi.yaml"
API設計ルール
- エンドポイントに必ず入力バリデーションを入れる（Zod必須）
- エラーレスポンスは常に { error, code, details } 形式
- コントローラーを変更したら必ずopenapi.yamlも更新する
- 仕様書を更新したら
npx openapi-typescript openapi.yaml -o src/types/api.ts を実行
- カーソルページネーションを使用（オフセットページネーション禁止）
Apidog MCP × Claude Code——仕様と実装の同期を自動化
Apidog MCPサーバーを使うと、Claude CodeがMCP経由で最新のAPI仕様を直接参照しながらコード生成できる。
{
"mcpServers": {
"apidog": {
"type": "sse",
"url": "https://mcp.apidog.com/sse?apiKey=YOUR_KEY"
}
}
}
DEV Community実践報告（pipipi-dev, 2026年）では「Apidog MCP × Claude Codeで仕様書と実装のドリフト問題が完全に消えた。仕様を変更するとClaude Codeが即座に関連するコード・テスト・型定義を更新する」と報告されている。
仕様変更が発生した場合の更新フローは、Apidog上で仕様を修正→MCP経由でClaude Codeが変更を検知→関連ファイルを自動更新、という流れになる。チームメンバー全員が同じ仕様を参照するため、「誰かが仕様書を更新し忘れた」という状況が発生しにくい。
2026年のAPI選択フレームワーク
「RESTとgRPCどちらを選ぶべきか」という質問はよく見かけるが、正直なところ答えはケースバイケースとしか言いようがない。判断軸をまとめておく。
パブリックAPI・外部向け → REST + OpenAPI 3.1
複数クライアント（Web/Mobile）→ GraphQL（BFF用途）
内部サービス間通信 → gRPC
TypeScriptフルスタック → tRPC
| プロトコル | 最適なユースケース | 2026年の位置づけ |
|---|---|---|
| REST | 公開API・外部連携 | OpenAPI 3.1で標準化が進む。変わらず主力 |
| GraphQL | モバイル・多様なクライアント | 「GraphQLブーム→REST回帰」の後、BFF用途で安定 |
| gRPC | マイクロサービス間通信 | Protobufによりデータサイズが小さく高速。内部通信の標準になりつつある |
| tRPC | TypeScriptフルスタック | エンドツーエンド型安全。Next.js + tRPCが2026年のスタンダード |
2026年の現実として、最良のチームは複数を使い分けている。公開APIはREST（OpenAPI 3.1）、フロントエンドへのBFFはGraphQLまたはtRPC、バックエンドのマイクロサービス間はgRPC——という構成だ。
Claude Codeへの相談プロンプトはこうなる。
この要件に最適なAPI設計を推薦して：
- スマートフォンアプリ（iOS/Android）向けのAPI
- Web管理画面も同じAPIを使う
- データ量が多いが、クライアントによって必要なフィールドが違う
- チームはTypeScriptが得意
推薦理由と、選ばなかった選択肢の理由も教えて
大規模OpenAPI仕様書のリファクタリング——定量的な成果
Daniel Ancuta（2026年）が3,200行の単一OpenAPI YAMLファイルをClaude Codeでリファクタリングした事例が参考になる。
問題の状態：スキーマ重複が47箇所、$ref定義の混乱、命名規則の不統一という状態だった。
Claude Codeへの依頼：
このOpenAPI仕様書（openapi.yaml）をリファクタリングして：
1. 共通スキーマを components/schemas/ に分割
2. 重複するエラーレスポンス定義を統一
3. エンドポイントごとにファイルを分割（paths/users.yaml など）
4. スキーマ全体の命名規則をキャメルケースに統一
リファクタリング後も全てのエンドポイントが正しく参照されていることを確認して
成果：
- スキーマ重複：47箇所 → 共通コンポーネント12個に統合（重複ゼロ）
- ファイル構成：単一3,200行 → paths/・components/に分割（各ファイル平均80行）
- CI/CDバリデーション：
openapi-validatorエラーが32件 → 0件 - 作業時間：手動で数日かかる見積もり → Claude Code使用で約2時間
「手作業では心理的に取りかかれない規模でも、AIなら躊躇なく着手できる」というDaniel Ancutaの言葉は、大規模仕様書を抱えているチームに刺さる言葉だ。
セキュリティレビューも同時に実施する
仕様書のリファクタリング時に、OWASP API Security Top 10に照らしたセキュリティ審査も同時依頼できる。Claude Codeは仕様書全体を読んでいるため、実装を見なくても「誰がどのエンドポイントにアクセスできるか」の設計を仕様から読み解ける。
リファクタリング後の仕様書をOWASP API Security Top 10の観点でレビューして：
- API1: 壊れたオブジェクトレベル認可（IDが推測可能なエンドポイントがないか）
- API2: 壊れた認証（Bearer Token以外の認証フローの漏れ）
- API3: 過剰なデータ露出（レスポンスに含めるべきでないフィールドがないか）
- API8: セキュリティの設定ミス（デフォルト認証なしエンドポイントがないか）
問題があれば仕様書の修正案も一緒に出して
コードレビューの段階ではなく「仕様設計段階」でOWASPリスクを潰せる点が大きい。実装が進んでからセキュリティ問題を修正するコストは、設計段階で修正するコストの数倍になる。
Before/After
Before（コードファースト・仕様書後付け）
実装を先に書く
↓
後から仕様書を書く（面倒なので省略されがち）
↓
仕様書と実装が乖離
↓
「どっちが正しいの？」という混乱が続く
↓
仕様書を誰も信用しなくなる
After（スペックドリブン + Claude Code）
Claude Codeと仕様設計（30分）
↓
OpenAPI 3.1仕様書を作成・保存
↓
Claude Codeが仕様から実装・型定義・テストを生成
↓
仕様変更時は仕様書を先に更新
↓
Apidog MCP経由でClaude Codeが変更を反映
↓
仕様と実装が常に一致
まとめ
仕様書が死ぬプロジェクトを何度も見てきたが、原因はほぼ同じだった。実装が先で、仕様書が後回しになる。「仕様が先、コードが後」に変えるだけで、あの「どっちが正しいの？」というやり取りがなくなる。
試してみるなら、この順番が最もハードルが低い。
今すぐ（15分）：既存の1エンドポイントをClaude Codeに見せ、「このエンドポイントのOpenAPI 3.1仕様書を生成して」と依頼する。生成された仕様書と実際の実装を見比べると、乖離している箇所がすぐ見つかる。
今日中：.claude/rules/api-design.md を作成し、チームのAPI設計ルール（エラーレスポンス形式・ページネーション方針など）を定義する。これで次のエンドポイント実装から自動的にルールが適用される。
チーム展開：新機能の開発では「仕様書を先に書く」ルールをチームで試験導入し、Apidog MCPをClaude Code環境に追加して仕様変更→自動コード更新のパイプラインを構築する。Daniel Ancutaの事例のような大規模リファクタリングとセキュリティレビューの同時実施も、この基盤があれば現実的な選択肢になる。
コメント