AIコーディングツール導入でAPI設計が崩れる落とし穴と対策

AIコーディングツール（GitHub CopilotやClaude Codeなど、コードを自動生成する開発支援ツール）を使い始めたチームで、API設計が知らないうちに壊れていくケースがあります。エンドポイント（APIの呼び出し先URLの単位）の命名や責務がばらばらになり、数か月後に統合コストが跳ね上がる現象です。

この記事は、AIツールでバックエンドAPIを量産しているエンジニア・テックリード向けに書いています。自分のプロジェクトが該当するかを確認する方法と、崩れる前に手を打つ手順をまとめました。

何が起きるか：画面駆動のAPIが量産される

AIコーディングツールにチケット単位で実装を依頼すると、画面や機能ごとにエンドポイントが生成されがちです。

たとえば「注文一覧画面を作って」と依頼すると GET /get-user-orders のような、画面の都合に合わせたエンドポイントが生成されます。

次に「決済処理を実装して」と別のプロンプトで依頼すると、今度は POST /submit-payment という別の命名規則のエンドポイントができあがります。

この状態を「画面志向（screen-oriented）」のAPI設計と呼びます。対して、業務capability（ビジネス上の機能単位）を軸にすると POST /products や GET /orders のような、リソース中心の一貫した設計になります。

画面志向のAPIが増えると、Webアプリ・モバイルアプリ・パートナー連携それぞれで同じ業務ロジックが重複実装されます。AIツールは目の前のタスクを最短距離でこなすため、この重複を自分から検知してはくれません。

なぜ起きるか：プロンプトとコンテキストの分断

原因を段階的に分解すると、3つのレイヤーに分かれます。

1つ目は、プロンプトの粒度の問題です。チケット単位・画面単位でAIに指示を出すと、AIは「そのタスクを完了させる最小のコード」を返します。既存のAPI一覧全体を見た上での提案にはなりません。

2つ目は、コンテキスト（AIに渡す前提情報）の欠如です。AIコーディングツールは、リポジトリ内の既存コードを参照はしますが、明示的に「既存のAPI設計規約」を渡さない限り、過去のエンドポイント命名パターンを一貫して踏襲するとは限りません。プロジェクトによって参照範囲や精度にばらつきが出ます。

3つ目は、レビュー体制の問題です。AIが生成したコードは動作確認さえ通れば通ってしまいがちで、「このエンドポイントは既存の /orders と統合できないか」という設計レベルのレビューが後回しになります。結果として、技術的負債ならぬ「API負債」が蓄積します。API負債は、コードの品質問題と違って、統合の段階になるまで表面化しにくい特徴があります。

自分のプロジェクトが該当するか確認する

実際に確認できる方法を3つ挙げます。

エンドポイント一覧の棚卸し

OpenAPI（RESTful APIの仕様を記述する標準フォーマット）を使っているなら、まず定義ファイルを一覧化します。

# openapi.yaml内のpath定義だけを抽出する
grep -E '^\s+/' openapi.yaml | sort

動詞ベースの命名（/create-product、/get-user-orders、/submit-payment）が混在していれば、画面志向のAPIが積み上がっているサインです。

同じ業務ロジックの重複を探す

# 「注文」「order」関連の処理がコントローラ層に何箇所あるか確認する
grep -ril "order" src/controllers | wc -l

件数が多く、かつ実装内容が似通っている場合、Web用・モバイル用・パートナー用でそれぞれ別のエンドポイントを作ってしまっている可能性があります。

Git履歴でプロンプト由来の設計揺れを追う

AIツールとの対話ログやコミットメッセージに「Copilot提案」「Claude生成」といった記録が残っている場合、それらのコミットで追加されたエンドポイントの命名規則を比較します。担当者やセッションが変わるたびに規約が変わっていないか確認する材料になります。

対策の手順

1. capability単位でAPIを再定義する

画面や機能ではなく、業務capability（ユーザー管理・商品・在庫・注文・請求など）を軸にエンドポイントを整理し直します。/get-user-orders は /orders に統合し、フィルタ条件はクエリパラメータで表現する形に寄せます。

2. AIツールに設計規約をコンテキストとして渡す

CopilotやClaude Codeを使う場合、リポジトリ直下に設計方針を明文化したファイルを置きます。

# api-conventions.yaml の例
naming: "リソース名は複数形の名詞のみ。動詞は使わない"
examples:
  good: ["/products", "/orders", "/payments"]
  bad: ["/create-product", "/get-user-orders"]
reuse_policy: "既存エンドポイントで対応可能な場合は新規作成しない"

Claude Codeであれば CLAUDE.md、Cursorであれば .cursorrules のように、ツールごとに読み込まれる規約ファイルの置き場所が決まっています。使っているツールの公式ドキュメントで、プロジェクト固有ルールをどのファイルに書けば自動で読み込まれるかを確認してください。

3. 生成コードのレビューに設計チェックを追加する

Pull Requestのテンプレートに「既存エンドポイントとの重複確認」「命名規則の準拠確認」の項目を追加します。AIが生成したコードかどうかに関わらず、この2点は機械的にチェックできる項目です。

4. MCP（Model Context Protocol、AIツールが外部システムと連携するための共通規格）でAPI仕様書を参照させる

OpenAPI定義をMCPサーバー経由でAIツールに公開すると、新しいエンドポイントを提案する前に既存API一覧を検索させることができます。すでに /orders が存在するのに /get-user-orders を新規提案する、という事態を減らせます。導入時は、利用しているAIツールがMCP対応済みかをまず確認し、対応していれば既存のOpenAPI定義をそのままMCPサーバーの情報源として使えるかを確認するのが近道です。

AIツールに「速く作らせる」ことと「一貫した設計を保つ」ことは別の課題であり、後者は規約ファイルとレビュー体制で人間側が補う必要があります。

まとめ

AIコーディングツールは実装速度を上げますが、API全体の一貫性までは保証しません。

エンドポイント一覧を grep で棚卸しし、動詞ベースの命名が混在していないか確認する
業務capability単位でAPIを再設計し、画面単位の重複実装を統合する
CLAUDE.md や .cursorrules など、使用中のAIツールが読み込む規約ファイルに命名規則を明文化する
MCP対応ツールなら、既存API仕様書を参照させて重複提案を防ぐ

まずは手元のOpenAPI定義かコントローラ一覧を一度棚卸ししてみることから始めてみてください。