【ITニュース解説】When AI Starts Writing Your System, Who Tells It What 'Done' Means?

AIを使ったシステム開発が注目を集めているが、そこには初心者が見落としがちな落とし穴がある。AIは非常に高速にコードを生成できるため、「予約システムを作ってほしい」と指示すれば、ユーザーが時間を選択し、予約を送信し、管理者がキャンセルできるようなシステムをあっという間に作り出す。ページの見た目も、データをやり取りする仕組み（エンドポイント）も、データを保存する場所（データベースのテーブル）も、一つ一つ見れば正しく作られているように見えるだろう。

しかし、これらのバラバラに作られた部品を実際に繋ぎ合わせてみると、予期せぬ問題が発生することがよくある。例えば、ユーザーが見る画面（フロントエンド）では時刻を現地時間として扱っているのに、裏側で動くサーバー（バックエンド）では協定世界時（UTC）として時刻を保存しているために、時間帯がずれて表示されるかもしれない。予約をキャンセルするための処理（キャンセルエンドポイント）は「成功しました」という返事を返すのに、予約の一覧画面にはまだ「予約済み」と表示されたままになることもある。さらに悪いケースでは、同じ時間枠が二重に予約されてしまうといった問題も発生しうる。

なぜこのような問題が起こるのだろうか。AIは大量のコードを素早く生成するが、「正しいシステム」とは何かという定義が、人間とAIの間のチャットのやり取りの中に断片的にしか存在しないことが多いからだ。その結果、システムを構成する一つ一つの部品（モジュール）が、それぞれ独自の「正しさ」を解釈して作られてしまい、全体として連携したときに矛盾が生じてしまうのだ。AIによるコーディングを成功させるためには、人間とAIが共通して参照できる「設計図」のようなものが必要なのである。

その設計図の一つとして注目されているのが、「OpenAPI Specification (OAS)」だ。OASは、APIと呼ばれるシステム間のデータのやり取りのルールを、誰でも理解できる形式で記述するための国際的な標準規格である。このOASには、どのようなデータを送ればいいのか、どのような形式で返ってくるのか、どんなエラーが起こりうるのかといった情報が、構造化された形で記述されている。人間が読んでも理解できるし、AIのようなツールもこの設計図を正確に読み取って、それに従ってコードを生成したり、検証したりできるのだ。

Powerduckというツールを使った開発の例を見てみよう。ここでは、まずビジネス要件、つまり「どのようなシステムを作りたいか」という大まかな要求をAIに伝える。そして、AIに既存のOASを参照させながら、その要求を満たすようなAPIの設計案を提案させるのだ。例えば、「予約の作成とキャンセルのAPIを設計してほしい。タイムゾーンの形式、予約の状態がどのように変化するか、そして予約済みの時間枠が選択されたときのエラー応答について明確にしてほしい。要件から明らかでないルールも洗い出してほしい」といった具体的な指示をAIに与える。

このとき重要なのは、AIがどれだけのコードを生成したかではなく、AIがAPIの設計図（OAS）にどのような変更を提案してきたかである。提案された変更点を見て、フィールドの意味が曖昧でないか、予約の状態モデルが一貫しているか、フロントエンドが必要とする失敗時の表示情報がきちんとカバーされているかなどを人間がレビューする。そして、その変更案（差分）を承認し、ローカルに保存されているOASファイルに反映させるのだ。これにより、チャットの履歴の中に埋もれてしまいがちな議論の内容が、プロジェクトの資産として永続的な形で残る。

OASは設計段階で一度作って終わりではない。Powerduckのような開発の流れでは、OASは開発プロセスのさまざまな段階で情報源として活用され続ける。

まず、「設計」の段階では、AIが既存の定義（OAS）に基づいてエンドポイントやデータの構造（スキーマ）の変更を提案する。

次に「実装」の段階では、AIのコーディングアシスタントが、OASに書かれた具体的な契約情報に基づいてコードを生成する。これにより、AIは単なるテキストの指示ではなく、正確な設計図に沿って作業を進められる。

また、他の部品（例えばフロントエンド）の開発が完了するのを待つ間、「依存関係待ち」の状況でもOASは役立つ。OASに記述された例やデータの構造（スキーマ）に基づいて、仮の応答を返す「モックサーバー」を立ち上げることができる。これにより、フロントエンドの開発者はバックエンドの準備ができていなくても、モックサーバーからの応答を使って開発を進めることが可能になる。

そして「検証」の段階では、AIエージェントがOASに書かれた契約に基づいて、実際にシステムにリクエストを送信し、応答が契約通りか、シナリオ通りに動作するかを自動的にテストする。

最後に「デリバリー（公開）」の段階では、OASファイルから自動的にAPIの利用マニュアルが生成され、必要に応じてエンドポイントを公開することもできる。

このように、OASを使うことで、AIが開発を進める上での「文脈」が、誰かがチャットで何度もコピー＆ペーストして与える必要がなくなり、設計段階からOASが唯一の真の情報源として開発全体を貫くようになるのだ。

AIによる開発では、「フィードバックループ」が極めて重要である。予約APIが完成した後、AIがOASに定義された契約に基づいてテストサービスにリクエストを送信し、その応答を検証できる。もしパラメータの不一致があったり、期待する応答フィールドが欠けていたり、あるシナリオが途中で機能しなくなったりした場合、それが次の改善のための具体的な手がかりとなる。AIが「完了した」と報告するだけではなく、実際の応答やテスト結果を詳細に分析することが重要だ。どのステップが成功し、どのフィールドが契約に合致しなかったのか、まだどんなルールが不足しているのか、といった具体的な情報が次の改善に繋がるのである。

もちろん、OASにも限界はある。例えば、複数のユーザーが同時に予約しようとしたときの競合状態や、複数のサービスにまたがる複雑な取引、あるいはビジネス上のあらゆる複雑な制約条件をOASだけで表現することはできない。これらを完全に検証するには、さらに具体的なシナリオテストや、実装レベルでの詳細なテストが必要になる。しかし、Powerduckのようなツールが目指しているのは、システム間の契約という構造化された情報をフィードバックループに組み込むことで、初期段階で多くのギャップを発見できるようにすることなのである。

このOASファイルは、ローカルのプロジェクト内に保存され、他のコードと同じようにバージョン管理システムで管理される。これにより、コードの変更履歴を追跡したり、以前の状態に戻したり、チームメンバー間でレビューしたりできる。もし将来、利用するAIのクライアントツールを変更したとしても、APIの契約情報はOASファイルの中にしっかりと残っているため、過去のチャット履歴から要件を再構築する手間はかからない。

「ローカルファースト」とは、単にオフラインで作業するという意味ではない。たとえクラウド上のAIモデルを利用する場合でも、AIに渡す文脈はローカルのファイルから送信される。この考え方の本質は、設計図となるファイルや日々の開発ワークフローが、特定のベンダーのチャットウィンドウに閉じ込められるのではなく、常にプロジェクトチーム自身の手元にあるということなのだ。

Powerduckは、現在のシステム開発で一般的になりつつある開発パターンを中心に構築されている。それは、人間が全体の目標と範囲を設定し、AIが設計と実装のプロセスに参加し、そして様々なツールがその成果が正しいことを検証する、という流れである。この開発サイクルにおいて、ローカルに管理されたOASは、人間、AI、そして検証ツールという三者をつなぐ、まさに接着剤のような役割を果たすのである。AIがコードを書き始める前に、「私たちは何を作っているのか」という共通の認識と、「それが正しいとどうやって確認するのか」という検証の基準が、一つの共有された場所に着地していることが、成功への鍵となるのだ。