生成 AI で仕様書のないレガシーコードから仕様を復元する手順

結論から書くと、生成 AI による仕様の復元で最も大事なのは、AI の出力を「確定」「推定」「不明」に分けて、根拠となるファイルと行番号を必ず付ける ことです。AI はコードの読解を大きく速くしますが、推測を事実のように書くことがあります。根拠のない説明は、仕様書の形をした思い込みになります。

また、コードから分かるのは「何をしているか」までです。「なぜそうしているか」と「それが正しいか」は、業務を知っている人にしか分かりません。

全体の流れは次の6段階です。

1. 入力してよいデータの範囲を決める
2. 入口を洗い出す
3. データの構造を把握する
4. 業務の単位で仕様を書き起こす
5. 人が検証する
6. テストで動きを固定する

準備: 入力してよいデータの範囲を決める（手順1）

最初にやるべきは、コードを読ませることではなく、読ませてよいものを決める ことです。

• お客様のシステムなら、秘密保持契約や業務委託契約で外部サービスの利用が制限されていないかを確認する
• 利用する AI サービスの利用条件で、入力データの学習利用や保存期間を確認する
• 接続情報、API キー、.env は読ませない
• データベースの中身をそのまま入れない。個人情報はマスクしたデータか、構造の情報だけを使う

個人情報については、個人情報保護委員会の注意喚起が参考になります。個人情報を含むプロンプトを入力する場合は利用目的の達成に必要な範囲かを確認すること、個人データが応答の出力以外の目的で扱われると法律に違反する可能性があるため、機械学習に利用されないことなどを十分に確認すること、とされています。

読み解く: 入口とデータの構造を把握する（手順2・3）

手順2: 入口を洗い出す

全ファイルを順に説明させても、まとまりのない文章が量産されるだけです。処理が始まる場所を先に一覧にします。

• URL とルーティング（フレームワークのルート定義、公開ディレクトリの PHP ファイル）
• 定期処理（crontab、バッチ、スケジューラの定義）
• 外部からの受け口（API、Webhook、メールの受信処理、ファイル連携）

定期処理の定義はコードの外、サーバー上にあることも多いので、AI に探させるだけでは足りません。サーバーの設定は人が確認して渡します。

依頼文の例です。

このリポジトリの処理の入口を一覧にしてください。
URL、対応するファイルと関数、認証の有無を表にします。

- 推測で補わず、確認できたものだけを書く
- 各行に根拠のファイルパスと行番号を付ける
- 判断できないものは「不明」とし、その理由を書く
- 動的に組み立てられているルートは別に一覧にする

古い PHP では、動的なメソッド呼び出し、文字列で組み立てたファイルの読み込み、.htaccess での書き換えなどがよく使われます。ここは AI も人間も見落としやすい箇所なので、別枠で確認します。

手順3: データの構造を把握する

処理の入口が分かったら、次はデータです。

業務システムの仕様の中心はデータです。画面より先にテーブルを見ると、全体の見通しが立ちます。

スキーマとテーブルごとの件数、更新日時の範囲を取得し、これを AI に渡して整理させます。外部キーが定義されていない古いシステムでも、カラム名やクエリの書き方から関連を推定できます。ただし、これはあくまで推定として扱います。

特に、状態を表すカラムは重点的に調べます。status の値が何を意味し、どの処理で変わるのかが分かると、業務の流れがかなり見えてきます。値の一覧は実データから取り、コードの定義と食い違うものは確認事項にします。

ここまでの結果を、画面や処理とテーブルの対応表にまとめておきます。どの処理がどのテーブルを読み書きしているかが分かると、影響範囲の調査にも、次の手順の書き起こしにも使えます。

AI に読ませるときは、一度に全部を渡さず、対象を絞ります。大きなシステムでは、範囲が広いほど説明があいまいになります。業務や機能ごとに会話を分けて、結果は会話の外のファイルに保存しておくと、会話が長くなっても前の調査が失われません。

書き起こす: 業務の単位で仕様にする（手順4）

ファイルごとではなく、「受注を登録する」「月次の請求を締める」のように業務の単位で書きます。使う人が読めるようにするためです。次の形式を決めて、出力を揃えます。

## 業務名: 受注の登録

### 概要
（誰が、いつ、何のために行うか）

### 処理の流れ
1. （内容） [確定] controllers/Order.php:120

### 入力チェック
- （内容） [確定] controllers/Order.php:88

### 更新するデータ
- orders に登録 [確定] models/Order.php:45

### 例外的な処理
- 特定の取引先のみ税計算が異なる [確定] models/Order.php:210
  理由は不明。担当者への確認が必要

### 確認事項
- （人に聞くべきこと）

重要なのは3つの区分です。

例外的な処理は特に重要です。条件分岐の中の特定の ID や取引先の扱いは、書き間違いに見えても、業務上の取り決めであることが多いからです。AI が「整理できる」と言っても、理由が分かるまでは消さないでください。

確かめる: 人の検証とテストで固定する（手順5・6）

手順5: 人が検証する

AI の出力はレビュー前の下書きとして扱います。検証は3つの方向から行います。

コードで確かめる。 根拠の行番号を開いて、書かれている内容と合っているかを確認します。全部は無理なので、金額計算、権限、データ更新など影響の大きい箇所を優先します。別のセッションに、仕様書の記述とコードの矛盾を探させるのも有効です。

動かして確かめる。 検証環境で実際に操作して、データベースやログの変化を見ます。仕様書に書かれたとおりの結果になるかを、代表的な例と例外の両方で確認します。動かせる環境がないなら、この段階を「未検証」と記録します。

人に確かめる。 担当者に業務の単位で読んでもらいます。技術用語を減らし、「この場合はこうなりますが、合っていますか」と聞くと、答えが返ってきやすくなります。前任者がいなくても、利用者なら業務の正しい動きを知っています。

手順6: テストで動きを固定する

文章の仕様書は放っておくと古くなります。重要な処理は、今の動きをテストとして固定します。入力と現在の出力を記録して、変わっていないことを確かめるテストです。

この種のテストは AI が得意な領域です。ただし、「今の動き」が正しいとは限りません。テストが固定するのは今の動きであって、不具合が見つかった場合は、修正するかどうかを業務の担当者と相談します。

仕様書はコードと同じ場所で管理し、処理を変えるときは同じコミットで更新します。「確定」「推定」「不明」の区分も残したままにしておくと、後から読む人が、どこまで信用してよいかを判断できます。検証が済んだ項目は日付と確認した人を書き添えておくと、次の引継ぎでも役に立ちます。

AI では分からないこと

最後に、限界をはっきりさせておきます。

• なぜそうなっているか。 経緯や取り決めはコードに残っていません。
• 実際に使われているか。 コードがあることと、使われていることは別です。アクセスログや更新日時と突き合わせます。
• 本番の環境に依存する動き。 サーバーの設定、本番だけの修正、定期処理の設定はリポジトリにありません。
• 正しいかどうか。 仕様の正しさを判断できるのは、業務を知る人だけです。

h-system でできること

h-system では、資料のないシステムの調査にも AI を活用し、結果の確認と判断は開発者が行っています。AI の出力をそのまま渡すのではなく、ソースコード、データベース、サーバー環境を確認して、構成とリスクを整理します。システムの引継ぎや調査は保守のサービスとして、AI の業務への取り入れ方はコンサルティングとしてご相談いただけます。初回相談（オンライン30分程度）は無料で、代表が直接対応します。