はじめに
業務システム開発において、「画面仕様書のメンテナンス」は常に頭の痛い問題です。
- 文字ベースの仕様書では、画面上のどの要素を指しているのか紐付けが分かりにくい
- かといって画面キャプチャを貼り付ける運用は、UI変更のたびに差し替えが必要で管理コストが大きい
- 画面ごとに仕様書を作ると数が膨大になりメンテナンスが追いつかない
- 処理内容を詳細に書くほど記述量が膨らみ、メンテ負荷も抜け漏れも増える
この課題に対し、「AIを使ってソースコードから画面仕様書を自動生成し、画面と一体化させて参照できるようにする」 という手法を構築しました。本記事では、その全体像と、現在構想中のMCPサーバー連携までをご紹介します。
1. AIエージェントで画面仕様書を自動生成する
仕様書作成のとっかかりとして用意したのが、AIエージェント向けの 再利用可能なプロンプト(スキル) です。画面仕様書を定義したJSONファイルを作成するスキルを定義しておくことで、
「画面仕様書を作成して」「
xxx画面の仕様書JSONを作って」
と指示するだけで、対象画面のソースを再帰的に解析し、画面仕様が定義されたJSONファイルが出力されます。
ポイント:解析対象はページに紐づく全コンポーネント
スキルのプロンプトでは「ページ → 子コンポーネント → 孫コンポーネント → ひ孫…」と 末端まで再帰的に辿る ことを明示しています。AIが浅い階層で打ち切るのを防ぐため、チェックリストも仕込んでいます。
[ ] ページ内にタブ切り替えで表示される子コンポーネントがある場合、
各タブコンポーネントのソースを読み込み、
内部の全フォーム要素・表示要素を elements に定義した
[ ] 子コンポーネントが更にサブタブや子コンポーネントを持つ場合も
再帰的に末端まで定義した
副次効果:仕様書を作る過程で実装の問題が炙り出される
AIが処理フローをステップ化していく過程で、「この分岐は意図通り?」「このエラーハンドリングは本当に必要?」といったレビュー観点が浮かび上がってきます。ドキュメント生成と同時にコードレビューが回る、というのは想定外の収穫でした。
2. 画面上で仕様書を確認できるViewer
JSONを生成しただけでは、結局PDFが増えるのと変わりません。そこで、実画面と仕様書を1対1で紐付けて表示する仕様書Viewer を画面に組み込みました。
開発環境で特定のキー入力をすると、ドロワーとしてViewerが立ち上がります。表示内容は4つのタブで構成されています。
ページ情報タブ
画面の説明・画面ID・ファイルパス・関連するAPI一覧を参照できます。
初期表示タブ
初期表示時に実行している処理を参照できます。
API一覧タブ
関連するAPIの概要・URI・リクエスト/レスポンス仕様を参照できます。これらの仕様内容はAPI経由で取得しています。
要素タブ
画面上のフォーム要素・ボタン要素・動的表示値の仕様を参照できます。
- フォーム要素:バリデーション情報
- 動的表示値:どのAPIのどのフィールドが表示されているか
- ボタン要素:非活性条件やクリックイベントの処理
仕組み:data-spec-id で要素とJSONを紐付ける
Viewerの肝は、画面の要素をクリックすると対応する仕様が即座に開く という操作感です。これを実現しているのが、スキルが自動付与する data-spec-id 属性です。
<!-- ページのルート -->
<div data-spec-id="spec:screen1-elementA">
<!-- フォーム要素 -->
<div data-spec-id="spec:login:screen1-elementB">...</div>
<!-- ボタン -->
<button data-spec-id="spec:login:screen1-elementC">ログイン</button>
<!-- 動的表示値 -->
<p data-spec-id="spec:screen1-elementD">...</p>
</div>
仕様書モードを有効化するとホバーで要素がハイライトされ、クリックするとViewerの該当箇所にジャンプします。たとえば一覧テーブルのセルをクリックすれば、
「このセルは
getUserListAPI のusers[].nameを表示している」
と即座に確認できます。「この値どこから来てるの?」を grep する時間がほぼゼロになりました。
3. 仕様書とAPI仕様をDBに集約し、開発管理ツールと共有
ここまでは1つのプロダクト内で完結する話ですが、さらに踏み込んで 仕様書JSONの内容を共通DBに格納 しました。
弊社では業務SaaS「Hirameki 7」の開発において、利用しているAPI・テーブル構造・システムコードを「SEVEN'S DOOR」という自社開発管理ツールで一元管理しています。ここに画面仕様も追加で持たせる形にしました。仕様データの多重管理を避けるため、共通DBを唯一の参照元とし、SEVEN'S DOORからもHirameki 7からも同じ内容を取得する構成にしています。
スキル側でもこの連携を考慮し、生成する仕様書には共通DB側のAPI情報と紐付くための識別子を必ず含めます。共通DBのAPI一覧とリクエストURIで突き合わせて自動で紐付ける手順を、スキル内に明文化しています
これにより、「Hirameki 7の画面で表示しているAPIの正規仕様は、SEVEN'S DOORで管理しているマスタと常に一致する」という状態が実現できました。仕様変更時の二重管理コストもありません。
4. 仕様DBをMCPサーバー化してAIから引けるようにする(構想)
ここからが現在進行中の取り組みです。仕様情報がDBに集約された以上、これを MCP(Model Context Protocol)サーバー として公開すれば、AIエージェントが直接クエリできるようになります。
イメージしているユースケース:
| 開発者の質問 | MCPサーバーが返すもの |
|---|---|
| 「ユーザー一覧取得APIを使っている画面一覧を教えて」 | API → 画面の逆引きリスト |
| 「ユーザー管理画面で必須項目になっているフォーム全部教えて」 | 画面仕様の要素一覧から必須項目を抽出 |
「POST /api/xxx を変更した際の影響範囲は?」 |
API変更時のリグレッションテスト範囲 |
| 「この画面の処理フローをシーケンス図にして」 |
processFlow を mermaid 変換 |
ドキュメントは「読む」だけでなく 「機械可読なAPIとして提供する」 ことで、AI支援開発のレバレッジが一気に高まります。MCP化後は、各種AIエージェントから「コードを読む」のと同じ感覚で「仕様を読む」ことができるようになる見込みです。
まとめ
| 課題 | 解決アプローチ |
|---|---|
| 仕様書のメンテコスト | AIエージェント向けスキルで自動生成 |
| 「この値どこから来てる?」 |
data-spec-id で画面↔仕様の双方向紐付け
|
| 開発管理ツールと画面仕様の二重管理 | 共通DBに集約してSEVEN'S DOOR(開発管理)とHirameki 7(プロダクト)で共有 |
| AI支援開発の精度向上 | 仕様DBのMCPサーバー化(構想) |
仕様書を「人間が書いて人間が読むだけのドキュメント」から、「AIが生成し、画面と紐付き、DBで共有され、AIから引ける機械可読データ」 へとシフトすることで、開発フロー全体が一段軽くなる手応えがあります。
同じような課題感をお持ちの方の参考になれば嬉しいです。