業務システムやサービス開発では、API仕様書を作成してから実装に落とし込むまでに、少なくない時間と確認コストがかかります。仕様の読み違い、実装粒度のばらつき、レビュー時の認識差などは、開発速度だけでなく品質にも影響します。
当社ではこの課題に対して、実装にけるドキュメントと JSON 形式の API 仕様書とサンプルコードをベースに、AI を活用して実装を自動化する取り組みを行なってます。単にコード生成を行うのではなく、既存のアーキテクチャや実装ルールに沿って、API 層、サービス層、バリデーション、DBモデル、テストまでを一貫して整備する開発フローです。
AIの実装に大きな制約を
AIによる実装支援が広がる一方で、「AIに自由にコードを書かせれば開発が速くなる」という考え方には注意が必要です。
特にAPI開発では、仕様書が整っていても実装段階で解釈の揺れが発生します。
たとえば、担当者ごとに責務の置き場所が変わったり、バリデーションやエラー処理の書き方が統一されなかったりします。レスポンス項目とデータベース項目の対応漏れや、仕様書から十分に引き継がれていないテスト観点も起こりやすいポイントです。
こうしたズレは、人が実装しても、AIが実装しても同じように発生します。むしろAIは、自由度が高いほど「それっぽい実装」を高速で量産してしまうため、ルールが曖昧な状態では、あとから修正コストが膨らみやすくなります。
そのため重要なのは、AIに自由を与えることではなく、あらかじめ大きな制約を与えることです。
当社では、AIに対して以下のような実装ルールを明文化しています。
- どの層に何を書くか。どこに何があるか。
- API層とサービス層（ビジネスロジック）の定義。各層での役割の明確化。
- インターフェース定義とバリデーション定義（場所・命名規則等）。
- データベースのエンティティとモデルの定義（場所・命名規則等）。
- 共通ユーティリティの利用、追加。
- コーディング規約（サンプルコードが担うかも）
このように、仕様だけでなく実装ルールまで先に固定しておくことで、AIはその範囲の中で安定したコードを生成できるようになります。
AIは万能ではありません。しかし、制約を与えられた環境では非常に強力です。
開発効率を高めるために必要なのは、「AIに任せる範囲を広げること」ではなく、「AIが迷わないように実装ルールを細かく定義すること」です。
実際にコーディング対象の仕様書をJSON形式で準備します。AI に渡す入力を単なる自然言語の依頼文ではなく、「実装に必要な構造化情報」にしていることが、今回の取り組みのポイントです。
人にお願いするよりもかなり丁寧な内容で、詳細設計レベルに近いものになるって感じです。実装をAIに任せる分、人として、ここはしっかり押さえておかないと。
最近は、詳細設計フェーズを省略する開発手法とかあったりと、その必要性が曖昧だったけどAIの台頭でそこはしっかり見直す時期に来ているかもです。
ざっと次のような内容を持たせています。
- API層（API名、メソッド、エンドポイント、バリデーション、HTTPステータスエラー、ミドルウェア）
- サービス層（リクエスト、レスポンス定義、エラーコード、メッセージ、処理内容、DB、外部API）
- テスト（正常、バリデーション、エラーコード毎のシナリオ）
- 改訂履歴
なんだかんだ言いながら、一番効くのはサンプルコードでしょうか。開発環境を一通り確認するので、コードがあれば、それに倣って実装を行うのがベースにあります。
AIに実装してもらう
準備ができれば、チャットからお願いします。今回の環境は、VsCode・Github Copilot(一部OpenAI)でnode.js・express・vitest・typormです。
「〇〇以下のドキュメント一式(*.md)とエンドポイント〇〇.jsonを参照して、エンドポイントとテストコードを実装しテストまで完了させて！」
AIはチャットの指示を受けて実装に入ります。プロセスを見ると実装前に、なんやら色々とやってます。
要求に合わせて、まず docs 配下の仕様と既存 API/テスト実装のパターンを確認し、〇〇.json に対応するエンドポイントとテストの差分を特定します。
docs の一覧と主要ファイルを見て、仕様と既存の実装パターンを対応付けます。次に必要なファイルだけ読み込みます。
既存の △△の 実装がかなり近いので、〇〇 は同じ層構造に沿って追加できそうです。次は仕様書と型・ルーティング・DB モデルをまとめて確認して、実装点を確定します。
型定義とルーティングを見る限り、〇〇 は未実装です。DB 更新系なので、エンティティ定義と既存テスト環境の初期化方法を見てから、そのまま実装に入ります。
エラーコードと既存のバリデーション部品を確認して、〇〇 用のリクエスト型と失敗ケースを仕様に合わせます。
実装方針は固まりました。tblKigyou の存在確認と insert/update をモデルに追加し、API/サービス/型/ルーティング/テストを一式実装します。失敗系は仕様の E0202 と E0203、予期しない例外は既存の E9999 に揃えます。
ServiceCode の扱いだけは仕様書に直接出ていないので、既存データの使われ方を確認します。そこが insert 時の実装上の唯一の曖昧点です。
これから 〇〇 用の型・モデル・API・サービス・テストをまとめて追加します。更新系なので、insert/update を部分更新に寄せて、未指定項目を保持する実装にします。
一式追加しました。ここで型エラーを先に潰してから、ビルドとテストに進みます。
型は通っています。ここからビルドと対象テストを実行して、失敗が出たらその場で修正します。
/〇〇 の実装とテストを追加し、ビルドと対象テストの通過まで確認しました。
追加したのは、API ルート corporation.ts、サービス層 corporation_service.ts、型とバリデーション mngserver.ts、保存用ヘルパーを足したモデル MdltblKigyou.ts、ルーティング登録 main.ts、そしてテスト corporation.test.ts です。仕様どおり、bnew=true の新規登録、bnew=false の更新、未指定項目の保持、E0202 と E0203 の業務エラー、例外時の 500 応答を実装しています。
確認結果は npm run build 成功、npm test -- src/__tests__/aitest/〇〇.test.ts で 5 件すべて成功です。テストは新規登録、部分更新、重複新規、存在しない更新、保存例外をカバーしています。結果的に言うと、実装は完了し、ビルドも実行し、指定した５つのテストシナリオも実装、テスト実施を見事に行ってくれました。１〜２人日の実装をわずか５分で終了した。
開発環境の構造もしっかり理解し、●がついているファイルが新規作成ないし、更新が行われたものです。
上から順に見ていくと。
テストデータをDBに保存し、指定したテストコードが実装、後始末もちゃんとしている。
APIインターフェースは今回はなかったのでAIが新たに追加・バリデーションzodで生成、指定したPOSTメソッドとパス名どおりのAPIが新たに生成された。
Modelはファイル自体は存在したが、サービス層で必要なDBアクセス部分は追加で実装されていた。
サービス層も基底クラスから派生する形で仕様通りの処理が新たに生成された。
指定したミドルウェアを経由させる感じでルート定義が追加されていた。
今回の案件は、リファクタリング案件を対象にしている。クライアントに了承のもと、今回の試みを行っており、リファクタリング案件を選択したのは、期待値が明確だからというのが理由で最終的な品質の検証がしっかり行える点です。
目標は、バックエンドをすべてAIに実装させることです。今回はDBに更新して返すと言った単純なものだったので、バリデーションの記述先が違うなという点を除いてはほぼ完璧に近かった。引き続き、検証を続けていきたい。
- フロント側の自動実装環境の構築
- 人とAIが理解できる仕様書のあり方の考察(仕様書もAIが改訂)
コードレビューの重要性
完全自動コーディングであっても、最終的な品質を担保するためには、人によるレビューが欠かせません。
特にバックエンドでは、認証漏れ、権限不備、例外処理不足、SQL条件の誤り、共有コードの利用など、小さなミスが大きな障害につながります。
そのため、AIが生成したコードをそのまま本番へ反映するのではなく、Pull Requestを通じてレビューを行うことが重要です。
最近では、実装だけでなく、Pull RequestレビューにもAIを活用できるようになっています。PRのテンプレートにAIへのプロンプトを記載しておけば、それに従いレビューを行ってくれます。
不具合の流出を防ぐのに大きな役割を果たしてくれるとても強い味方です。
基本Githubの場合はCopilotを使用すれば良いですが、弊社ではOpenAIで自由度の高いプロンプトでレビューシナリオを組む場合もあります。
おまけ ： 改訂履歴を理解してくれるか？
仕様の改訂は、欠かせないものです。仕様書のJSONに仕様の改訂と改訂履歴を盛り込みました。ちょっとAIに頼んでみます。
「〇〇以下のドキュメント一式(*.md)参照し、エンドポイント〇〇.jsonに改訂があるので実装して欲しい、実装対象は、最新の日付を参照すること！」
普通に実装してくれる模様。
ポイントは、改訂なので、既存のコードを大きく変えることなく実装してもらうこと。
改訂用のプロンプトを別途用意することにより、改訂の実装の精度を上げれそうだ。
