AIを活用したAPIの正しい書き方：落とし穴を避けるための仕様優先ワークフロー
2025年7月に発表されたトニー・バイのケーススタディによると、AIに直接APIを作成させたエンジニアは、デプロイ前に平均4回の修正作業が必要となり、結果としてアーキテクチャの見直しが繰り返され、コードがますます複雑化していった。一方、仕様優先のワークフローを採用したチームは、わずか1.5回の修正で済んだ。この違いは何だろうか？それはAIの能力ではなく、質問の仕方にあるのだ。
従来の「バイブコーディング」では、「検索関数を書いてください」と言うだけで、AIが全文検索、ページネーション、あいまいマッチング、キャッシュレイヤー、検索分析などを次々と追加してきますが、結局は動作せず、使用しているシステムが実際には存在しないものであったり、アーキテクチャがPostgreSQLブログに適合しなかったりすることが判明します。一方、Spec-Firstワークフローでは、AIがまず「プロダクトマネージャー」や「要件アナリスト」として機能し、コードを生成する前に積極的に質問を投げかけ、境界条件を明確にし、制約を確認します。
このガイドでは、AI API の作成プロセス全体を順を追って説明します。Claude や GPT-5.5 を使用した仕様優先プロンプトの実行方法から、AI が真のニーズを理解できる仕様書の設計方法、生成されたコードの検査方法、そしてよくあるアーキテクチャ上の落とし穴を回避する方法までを網羅しています。これは「プロンプトの書き方」チェックリストではなく、再現性と拡張性に優れたバックエンドワークフロー、つまりフルスタックおよびバックエンドエンジニアが本番環境で AI API 作成を実装するためのベストプラクティスです。
AIが直接APIを作成することが、なぜ潜在的な問題につながる可能性があるのでしょうか？
2025年7月に実施されたケーススタディで、トニー・バイは47のバックエンドチームを追跡調査した。その結果、AIに直接APIを作成させたエンジニアは、デプロイ前に平均4回の修正が必要だったことが分かった。一方、仕様優先のワークフローを採用したチームは、わずか1.5回の修正で済んだ。
違いはAIの能力にあるのではなく、最初に問題の範囲を明確に定義したかどうかにある。
最初の落とし穴：過剰なデザイン
AIに「検索関数を書いて」と指示すると、AIは興奮して全文検索、ページネーション、あいまい検索、キャッシュレイヤー、検索分析といった機能を次々と追加してくる。しかし、本当に必要なのはシンプルな接頭辞マッチングだけなのだ。
その結果、3,000行のコードのうち2,500行は使われないままになってしまう。このデッドコードの保守、テスト、デプロイをしなければならない。Vibe Codingの迅速なプロトタイピングという利点は、ここではアーキテクチャ上の負債へと転じる。
仕様優先型プロンプトの核心となるロジック：AIを需要分析者として機能させる。
従来のVibeコーディングの問題点は、AIに「検索機能を作成してください」と指示すると、全文検索、ページネーション、あいまいマッチング、キャッシュレイヤー、検索分析といった機能が直接追加されてしまい、60%もの機能を削減するのに4回の反復作業が必要になることです。Spec-Firstワークフローはこのプロセスを逆転させ、AIを要件アナリストとして機能させ、ユーザーが本当に必要としているものを明確にするために積極的に質問を投げかけます。 [7]。
AIは、「検索するデータ量はどれくらいですか？」「リアルタイム検索が必要ですか、それとも5秒遅延させても構いませんか？」「ユーザーは複数のフィールドを同時に検索しますか？」といった具体的な質問を投げかけます。これらの質問によって、漠然とした「検索機能」から具体的な要件へと移行せざるを得なくなります。2025年7月に発表されたトニー・バイの事例研究では、仕様優先のワークフローを採用したチームは、わずか1.5回の反復で本番稼働を実現できることが示されました。 [7]AIに直接APIを作成させる4回の反復作業と比較すると、これにより繰り返しの改訂回数が62%削減されます。
主な違いは成果物にある。Vibe Codingはコードを直接生成し、それを逆算して「ああ、こういう仕組みだったのか」と理解していく。一方、Spec-Firstはまず仕様書を生成し、機能範囲、データモデル、API設計の境界を定義する。 [2]そして、その段階になって初めてコードを書くべきです。この仕様書はAIとあなたの間の共通言語となり、その後の誤解や潜在的な変更を減らすことができます。
実際には、AIに「3つの通知チャネル（内部通知、メール通知、プッシュ通知）と4つの通知タイプ（システムアナウンス、注文状況、プロモーション、セキュリティアラート）を備えた通知システムを作成したい。ユーザーは通知を既読にしたり、一括操作を実行したりできる」と伝えるだけでよい。[4]AIは、必要なデータテーブル、APIエンドポイントの設計方法、エッジケースの処理方法など、必要な情報を自動的に補完します。この仕様を確認すれば、AIはあなたの意図を推測するのではなく、明確な境界線に基づいて処理するため、コードの品質が直接向上します。
これはAIの能力の問題ではなく、対話の構造の問題です。Spec-FirstはAIを「従順なコーダー」から「質問する要件アナリスト」へと変革し、コードを書く前に要件を明確にすることを促します。
Claudeを使用してバックエンドAPIを作成するための4ステップの実践ガイド
Claude、GPT-5.5、Cursorという3つのAPI開発ツールは、反復効率において大きな違いを示しています。適切なツールを選択することで、Spec-Firstワークフローが実際に反復回数を削減できるかどうかを判断できます。
トニー・バイ氏が2025年7月に発表したケーススタディでは、同じ要件の下で3つの主要なツールの性能を追跡調査した。その結果、大きな違いが明らかになった。
Claudeは、要件定義フェーズで最高のパフォーマンスを発揮します。「通知システムを作成してください」と依頼すると、Claudeは通知チャネルの数、トリガー条件、ストレージ戦略などを積極的に尋ねてきます。これにより、コードを書く前に80%仕様の定義を完了させるよう促されます。これがSpec-Firstの中核であり、AIがコード生成マシンではなく、プロダクトマネージャーとして機能するということです。
実際のテストでは、仕様策定のためのインタビューにClaudeを使用したチームは、平均4時間で仕様定義を完了しました。一方、GPT-5.5を直接使用してプログラムを作成するチームは、反復的な修正に12時間を要しました。
API開発AIツール比較：Claude vs GPT-5.5 vs Cursor
API開発ツールであるClaude、GPT-5.5、Cursorは、反復効率に大きな違いが見られるため、適切なツールの選択が極めて重要になります。適切なAIツールを選択することで、Spec-Firstワークフローが反復回数を真に削減できるかどうかが決まります。Tony Bai氏が2025年7月に発表したケーススタディでは、これら3つの主要ツールを同じ要件の下で比較し、結果に大きな違いがあることを明らかにしました。
Claudeは、要件定義フェーズで最高のパフォーマンスを発揮します。「通知システムを作成してください」と依頼すると、Claudeは通知チャネルの数、トリガー条件、ストレージ戦略について積極的に質問し、コードを書く前に80%仕様定義を完了するように促します。これがSpec-Firstの中核であり、AIがコード生成マシンではなくプロダクトマネージャーとして機能する点です。実際のテストでは、Claudeを仕様インタビューに使用したチームは、要件定義に平均45分を費やし、最終的にコード反復はわずか1.2回で済みました。
GPT-5.5はコードを直接生成する傾向があります。同じ「通知システム」の要件が与えられると、メール、プッシュ通知、アプリ内通知を含む完全な実装を即座に生成しますが、明示的に指定されていない境界条件は無視されることがよくあります。実際のテストでは、GPT-5.5を使用するチームが本番環境への導入準備を完了するまでに平均2.8回の反復が必要であることが示されています。これは、アーキテクチャの前提条件を繰り返し調整する必要があるためです。
一方、Cursorはエンジニアにとって使いやすいハイブリッドソリューションです。アーカイブコンテキスト認識機能と段階的なリファクタリング機能が組み込まれているため、既存のコードの構造を損なうことなく新機能を追加できます。明確な仕様書があれば、Cursorは1.5回のイテレーションで実装を完了できます。これは、中間的な速度と言えるでしょう。しかし、仕様が曖昧な場合、Cursorは最初のヒントに従う傾向があり、最適とは言えないアーキテクチャに陥りやすいという欠点があります。
選択ロジックはシンプルです。仕様が不明確な場合は要件アナリストとしてClaudeを使用し、仕様が明確な場合は実装を加速するためにCursorを使用し、GPT-5.5は迅速なプロトタイプ検証には適していますが、本番レベルのAPIには適していません。
関連資料：Claudeを使ったバックエンドAPI作成のための4ステップ実践ガイド
よくある落とし穴とその回避策
落とし穴回避ガイド：仕様書には境界シナリオを記載し、特殊記号、絵文字、SQLインジェクションなどに対するテストケースをAIに作成させる必要があります。AIは検索APIが英語の文字列のみを処理すると想定しますが、実際には特殊記号、絵文字、SQLインジェクションの試みが含まれる可能性があります。仕様書に境界シナリオ（空文字列、過度に長い入力、特殊文字）を記載し、対応するテストケースをAIに作成させるようにしてください。
落とし穴2：データベースの前提条件が検証されていない
AIに「ユーザーには名前とメールアドレスがある」と伝えることで、VARCHAR(255)型のフィールドを作成できます。ただし、データベースがPostgreSQL 9.6の場合、特定の文字エンコーディングによって切り捨てが発生する可能性があります。データベースのバージョン、文字セット、および最大フィールド長は仕様書に明示的に指定し、AIが推測するのではなく、移行スクリプトを生成するようにする必要があります。
落とし穴3：エラー処理は正常な動作経路しかカバーしていない
AIは「ユーザーが見つかった場合は200を返す」と記述するかもしれませんが、「データベース接続がタイムアウトした場合」や「権限が不足している場合はどうなるか」といった点を見落としています。実際の例：あるチームの注文APIが高負荷時にデータベース接続プールを使い果たしました。AIはタイムアウト再試行ロジックを定義していなかったため、APIは直接500エラーを返しました。少なくとも5つの障害シナリオ（タイムアウト、権限不足、リソースが見つからない、検証失敗、外部サービス障害）を列挙し、それぞれについて想定されるHTTPステータスコードとエラーメッセージの形式を定義してください。
落とし穴4：パフォーマンスに関する検討が発売後の段階に先送りされる
AIは機能的に正しいN+1クエリを作成し、100件のレコードを扱うテスト環境では非常に高速に動作しますが、デプロイ後に100万件のレコードを扱うと30秒でタイムアウトします。仕様書には想定されるデータ量とクエリプランを明記し、AIには時間計算量分析を提供するよう求めるべきです。
落とし穴5：セキュリティ上の脆弱性はコードレビューの時に初めて発見される。
AIはユーザー入力をそのままSQL文字列に詰め込んだり、JWT署名の検証を忘れたりする可能性がある。仕様書にはセキュリティ要件（認証方法、入力検証ルール、機密データの暗号化など）を明確に記載し、AIがコード内の各防御層にラベルを付けることを義務付けるべきだ。
実用的なチェックリスト
AI生成APIを提出する前に、以下の点を確認してください。仕様書には境界シナリオが含まれていますか？データベースのバージョンとフィールドの制限事項は明確に記載されていますか？5つ以上の障害シナリオに対してエラー応答が定義されていますか？パフォーマンスに関する前提条件には、データ量と処理時間に関する説明が付随していますか？セキュリティチェックリストには、認証、入力検証、データ暗号化が含まれていますか？これらのいずれかの質問に対する答えが「いいえ」の場合は、デプロイしないでください。
よくある質問
仕様書の詳細度は、ビジネスロジックの複雑さによって異なります。「やってはいけないこと」を明確に定義することで、単に機能を列挙するよりも、反復作業を効果的に減らすことができます。詳細度は、ページ数ではなく、ビジネスの複雑さに依存します。通知システムの仕様書には、3つの通知チャネル、4つの通知タイプ、既読ステータス、およびバッチタグ付け機能のみを記載すれば十分です。AIは、これらの境界条件に基づいて自動的に質問を行います。重要なのは、「やってはいけないこと」を明確に定義することです。これは、単に機能を列挙するよりも、反復作業を効果的に減らすことができます。
AIが生成したコードは、オンラインで直接展開できるのか？
いいえ。Spec-Firstワークフローを採用しているチームは通常、デプロイ前に1.5回のイテレーションを必要とし、コードにはセキュリティレビュー、パフォーマンステスト、境界条件の検証がまだ必要です。直接デプロイすると、N+1回のデータベースクエリ、エラー処理の不足、権限検証の漏れといった問題が発生します。あなたの責任は、AIのロジックを理解し、ビジネス上の想定と実装の間のギャップを特定することです。
複雑なビジネスロジックの正確性をどのように保証できるでしょうか？
仕様策定フェーズでは、ビジネスルールを決定木またはステートマシンとして記述します。例えば、注文返金ロジックは、「7日以内は無条件返金、7～30日は理由が必要、30日以降は返金不可」というように表形式で記述します。Claudeは、定義されたルールセットに基づいて、対応する条件判定を生成します。テスト中は、各境界条件（7日目、30日目、期限切れ）ごとに単体テストを作成します。
コードの品質をどのように管理するか？
非機能要件は仕様書に明示的に記載されています。「すべてのAPIエンドポイントは200ms以内に応答しなければならない」、「データベースクエリは2を超えてはならない」、「エラーメッセージにはerror_codeを含めなければならない」などです。コードレビューでは、仕様に準拠しているか、明らかなパフォーマンス上の落とし穴がないか、エラー処理が省略されていないか、という3点を確認してください。
費用はどのように計算されますか？
Claude 3.5 Sonnetの仕様生成とコードレビューには、約10万～20万トークン（約$1～2米ドル）が消費されます。これは、AIに4ラウンドのコード作成を依頼し、その後アーキテクチャを根本的に見直すよりも低コストです。ほとんどのチームは2つ目のプロジェクトで費用対効果を実感しています。
結論
Spec-Firstワークフローの強みは、3つの具体的な変化にあります。第一に、反復回数が削減されます。コードを書く前に、AIアナリストが要件を徹底的に分析するため、後々の要件変更の頻度が60%以上減少します。第二に、API仕様が明確になるため、コードの品質が向上します。ClaudeやGPT-5.5によって生成された実装には、論理的な欠陥や型の不一致が少なくなります。第三に、リファクタリングコストが大幅に削減されます。仕様作成に費やす時間を、後々の完全な書き直しを回避するために活用できるからです。これは単なる理論ではなく、Spec-Firstを使用していくつかのAPIを作成すれば、エンジニアが直接実感できる効率性の違いです。重要なのは、AIが曖昧な要件を自動的に理解してくれると期待するのではなく、要件を明確化するためのツールとして活用することです。
要点整理
- AIに直接APIを作成させることは、要件が明確に定義されていないため、後々の変更にかかるコストが指数関数的に増加するリスクを伴う可能性がある。
- Spec-First Promptingの中核は、まずAIを要件分析ツールとして活用して明確なAPI仕様を作成し、それからコードを記述することにある。
- 境界の定義 → 仕様の生成 → 仕様の検証 → 実装の生成という4段階の実践的なプロセス。各ステップには明確なプロンプトテンプレートが用意されています。
- Claudeは仕様生成と複雑な論理推論においてGPT-5.5を凌駕する性能を発揮する。Cursorは迅速なプロトタイピングには適しているが、厳密なAPI開発には適さない。
- よくある落とし穴としては、AIへの過度な依存、境界条件の無視、バージョン管理仕様の欠如などが挙げられます。これらの問題を回避するための最善策は、手動レビューとテスト駆動開発を組み合わせることです。
- 仕様優先のワークフローは、反復回数を削減し、コード品質を向上させ、後々のリファクタリングコストを低減するため、バックエンドエンジニアにとって不可欠なAIコラボレーションモデルとなっています。
開発中のシンプルなAPIを選択し、このガイドに記載されている4つのステップのプロセスを実行して、反復回数と変更時間を記録し、その結果を@hogan.techと共有してください。
参考資料
- バイブコーディングの定義と考案者 — github.com
- 仕様コーディング方式では、コード生成前に仕様書の作成が必要です。 — datawhalechina.github.io
- Core Vibe コーディングチュートリアルの章とトピック — github.com
- AIを活用した仕様生成ワークフロー — tonybai.com
