ドキュメントゼロのレガシーWebアプリを、AIで一括リバースエンジニアリングして仕様書を量産する

ドキュメントゼロのレガシーWebアプリを、AIで一括リバースエンジニアリングして仕様書を量産する

はじめに：ドキュメントのない保守案件という現実

長く運用されてきた業務Webアプリを引き継ぐと、たいてい同じ壁にぶつかる。仕様書が存在しない、あっても数年前のまま放置されている、そして書いた人はもういない。フロントは今ではメンテナンスされていない古いフレームワーク製で、画面数は3桁規模。どの画面がどのAPIを叩き、どの状態を持ち、どこをいじると何が壊れるのか。それを知る手がかりはコードだけ、という状況だ。

この状態で改修依頼が飛んでくると、まず「影響範囲の調査」に膨大な時間が溶ける。1画面直すために10画面読む、という非効率が常態化する。人力で全画面の仕様書を起こすのは現実的ではなく、結局「詳しい人の頭の中」に依存し続けることになる。

ここで取ったアプローチが、AIを使って全画面の仕様書を一括生成することだった。この記事では、その再現可能な手順と設計の勘所を、一般化してまとめる。

アプローチ1：仕様書テンプレートを先に固める

一括生成で最も重要なのは、生成させる中身のテンプレートを最初にきっちり定義することだ。ここが曖昧だと、画面ごとに粒度も項目もバラバラな文書が量産され、かえって読めなくなる。

今回は各画面につき、以下の固定項目を必ず埋めさせる形にした。

• **概要**：この画面が業務上どんな役割を担うか。1〜3行で。
• **UI要素**：フォーム、テーブル、ボタン、モーダルなど主要コンポーネントの一覧と役割。
• **呼び出しているAPI**：エンドポイント、メソッド、いつ呼ばれるか（初期表示／送信時など）。
• **状態管理**：この画面が保持・参照するステートと、その更新契機。
• **改修時の危険度スコア**：後述する定量スコア。

ポイントは「コードから機械的に判定できる項目だけで構成する」こと。ビジネス背景のような、コードに現れない情報は最初から求めない。AIが埋められない欄を作ると、そこが憶測で埋まって信頼性を落とす。埋められる欄だけに絞ることが、文書全体の信用を守る。

アプローチ2：画面単位で切って一括生成する

3桁規模の画面をまとめて1回のプロンプトに投げても、精度は出ない。文脈が薄まり、途中から手を抜いた出力になる。

有効だったのは「画面（ルーティング）1つを処理の最小単位にする」ことだった。ルーティング定義を起点に、各画面のエントリーコンポーネントと、そこから辿れる子コンポーネント・API呼び出し・状態管理のコードをひとまとめにし、1画面=1タスクとしてAIに渡す。テンプレートは共通、入力コードだけが画面ごとに差し替わる、という構造にする。

擬似コードで書くと、おおよそこうなる。

screens = collect_routes(project)   # ルーティングから全画面を列挙

for screen in screens:
    context = gather_related_code(screen)   # 画面から辿れるコードを収集
    spec = ai_generate(
        template=SPEC_TEMPLATE,             # 固定テンプレ
        code=context,
        instruction="コードに書かれた事実のみ記載。推測は明示",
    )
    write_markdown(f"docs/{screen.name}.md", spec)

このループ化には副次的な効果がある。1画面が独立タスクなので、失敗した画面だけ再実行できる。全体をやり直す必要がない。また画面ごとにファイルが分かれるため、後からの差分管理やレビューもしやすい。

指示文には必ず「コードに実在する事実だけを書き、不明な点は不明と書く」と入れておく。レガシーコードは変則的な書き方が多く、AIが辻褄合わせに走りやすい。憶測を禁じ、分からないものは分からないと言わせるほうが、保守文書としてはるかに使える。

アプローチ3：改修危険度スコアで、トリアージを自動化する

仕様書が揃っても、3桁の画面を前に「どこから手を付けるか」は依然として重い問いだ。そこで各画面に定量的な危険度スコアを付け、色分けした。

スコアは「壊れやすさ」と「壊れたときの影響」を分解し、複数の観測可能な指標を合算する方式にした。たとえば次のような軸を、それぞれ数段階で採点して合計する。

• 依存しているAPIの数（多いほど危険）
• 状態管理の複雑さ（グローバルな状態を触るほど危険）
• 他画面との結合度（共有コンポーネントや共有ステートへの依存）
• コードの規模・分岐の多さ
• テストの有無

これらを合算し、満点を10点強に設定して、高スコアほど「触ると危ない画面」とした。仕上げに、スコア帯で赤・黄・緑に色分けして一覧化する。

こうすると、改修トリアージが一気に軽くなる。緑の画面は安心して着手でき、赤の画面は事前調査・テスト補強・レビュー厚めといった段取りを最初から組める。スコアはAIの主観ではなく観測可能な指標の合算なので、なぜその点数かを後から説明できるのも実務上ありがたい。

得られたもの

この取り組みで得られたのは、単なる文書の束ではなかった。

第一に、**影響範囲調査の初速**が変わった。改修依頼が来たとき、まず該当画面の仕様書を開けば、叩いているAPIと持っている状態が一覧で分かる。「まずコードを読む」から「まず仕様書を読む」に入り口が変わる。

第二に、**トリアージの共通言語**ができた。危険度スコアという定量指標があると、着手順や見積もりの根拠をチームや依頼元と共有しやすい。「なんとなく怖い」が「スコアが高いから調査を厚くする」に変わる。

第三に、**属人性の緩和**だ。詳しい人の頭の中にしかなかった知識の一部が、検索可能なテキストとして外に出た。完全ではないが、依存度は確実に下がる。

注意点：鵜呑みにしない、腐らせない

最後に、導入する人向けの注意点を挙げておく。

**AI生成の仕様書は「一次調査の下書き」であり、正典ではない。** 特に危険度が高い画面ほど、着手前に人間が中身を検証すべきだ。生成物を信頼の起点にしてよいが、最終判断の根拠にしてはいけない。

**憶測の混入は必ず起きる前提で運用する。** どれだけ「推測禁止」と指示しても、変則的なコードでは辻褄合わせが混ざる。不明点は不明と書かせ、レビューで潰す運用をセットにする。

**文書は必ず腐る。** コードが変われば仕様書はずれていく。だからこそ一括生成をワンショットの作業にせず、再実行可能なパイプラインとして残しておく価値がある。変更のあった画面だけ再生成できる仕組みにしておけば、鮮度を保ちやすい。

ドキュメントのない保守案件は、これからも無くならない。人力で全画面を起こすのは非現実的でも、「テンプレートを固め、画面単位でループ生成し、定量スコアでトリアージする」という手順なら、現実的なコストで足場を作れる。完璧な仕様書ではなく、迷わず一歩目を踏み出せる地図をつくる。それがこのアプローチの狙いである。