はじめに：ドキュメントのない保守案件という現実
長く運用されてきた業務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生成の仕様書は「一次調査の下書き」であり、正典ではない。 特に危険度が高い画面ほど、着手前に人間が中身を検証すべきだ。生成物を信頼の起点にしてよいが、最終判断の根拠にしてはいけない。
憶測の混入は必ず起きる前提で運用する。 どれだけ「推測禁止」と指示しても、変則的なコードでは辻褄合わせが混ざる。不明点は不明と書かせ、レビューで潰す運用をセットにする。
文書は必ず腐る。 コードが変われば仕様書はずれていく。だからこそ一括生成をワンショットの作業にせず、再実行可能なパイプラインとして残しておく価値がある。変更のあった画面だけ再生成できる仕組みにしておけば、鮮度を保ちやすい。
ドキュメントのない保守案件は、これからも無くならない。人力で全画面を起こすのは非現実的でも、「テンプレートを固め、画面単位でループ生成し、定量スコアでトリアージする」という手順なら、現実的なコストで足場を作れる。完璧な仕様書ではなく、迷わず一歩目を踏み出せる地図をつくる。それがこのアプローチの狙いである。