理解しにくいレガシーシステムを、変更判断できる状態へ変える

使い続けるために、まず現行仕様へ到達できるようにする

対象は約20年前に当社の中心的なソフトウェアとして開発された、多機能なシステムだった。終了を検討したこともあったが、長年の利用者・愛用者が多く、単純には廃止できなかった。

ところが、問い合わせに答えるための情報が十分に共有されていなかった。

仕様書は存在したが、UIの説明が中心で内部仕様はほとんどなく、古い記述も更新されていなかった。現在の担当者も詳細を把握できず、長期間担当している委託作業者だけが知る情報もあった。

使い続ける以上、調査のたびに動作を確認し直す状態を変える必要がある。新規開発や全面刷新に先立ち、現行システムを理解し、何を変更できるか検討するための情報を再構成した。

仕様書の整理だけでは、問い合わせに答えられない

既存仕様書を読み直しても、実際にはソフトウェアを動かさなければ挙動を確かめられなかった。記載を整えるだけでは、欠けている内部仕様や処理の関係は埋まらない。仕様書が存在することと、仕様が管理されていることは同じではなかった。

そこで、資料を現行仕様の正本とはみなさず、ソースコードを起点にUI、実際の動作、既存文書、担当者の知識を横断して確認した。

AIにはコードの説明や構造の仮説を出させ、人間が実コードと実行結果を照合した。もっともらしい説明を、そのまま仕様として確定する工程にはしなかった。

この実践で使用した生成AIはGPTであり、当時の作業ではGitHub Copilotを利用していない。

復元した仕様を、人とAIが使える情報へつなぐ

クラスやファイルの役割を整理し、UI操作から処理の呼出しや分岐を追った。これにより、コードの所在だけでなく、操作・処理・結果の関係を確認する材料を作った。全体の構成は次のとおりである。

操作＋の付いた項目を選ぶと、詳しい説明が下に表示されます。

詳しい説明

気になる項目を選ぶと、その役割や判断理由を確認できます。

現行仕様が分からない

約20年前に開発された多機能なシステムで、長年の利用者がおり単純には廃止できませんでした。仕様書はUI説明中心で古く、問い合わせのたびに実機確認が必要でした。知識が長期担当者へ偏る状態を、仕様情報の不足として捉えました。

コード・動作を調査

ソースコードを起点に、UI、実動作、既存文書、担当者の知識を組み合わせて調べました。GPTにはコードの説明や構造の仮説を出させ、人が実コードと実行結果を照合しました。AIのもっともらしい説明を、そのまま仕様として確定しませんでした。

現行仕様を復元

処理・分岐・入出力・依存関係をコードから復元し、現行の動作として確認しました。全面刷新を先に進めるのではなく、廃止できないシステムを理解・変更判断できる状態へ戻すことを優先しました。

人向けの図

処理フローや要素間の関係を、人が俯瞰できる図と説明へ整理しました。文章だけでは組み立てにくい全体像を見える形にし、仕様確認や変更影響の調査に使いました。

AI向けの文書

確認した仕様の条件・例外・詳細を、検索しやすい文書中心のKnowledgeへ整理しました。人向けの図と表現は分けますが、情報の土台は同じです。利用者の操作に関する質問からも関連情報を探せる構成にしました。

QA・変更判断へ

調査結果を一回限りにせず、仕様確認・QA・継続保守へ再利用しました。AIは関連情報や判断材料を提供しますが、変更の採否は人が現在の状況を踏まえて決めます。理解を蓄積し、次の変更判断に使える状態を目指しました。

処理の流れ、要素間やシステム間の関係、運用手順は、自然言語だけでは追いにくい。図で確認できることに加え、仕様変更に合わせて更新できることも必要だった。

手作業で図を保守する方法ではなく、テキストから生成・更新できる処理構造の図を利用した。

一方、図をそのまま検索用の資料にするだけでは、質問に必要な根拠へ到達しにくい。

人向けには視覚的な構造を、AI向けには検索可能な文書中心のKnowledgeを用意した。

別々の仕様を持つのではなく、同じ仕様情報を、利用主体に合う表現へ分ける考え方である。

QAは答えを決める仕組みではなく、根拠へ戻る入口にする

復元した知識はRAG / QAへ接続した。内部のクラス名だけでなく、UI操作や「何をしたいか」という問いから参照できるようにし、回答範囲を対象システムのKnowledgeへ限定した。

情報がない場合まで推測で補わせないことを重視した。

仕様、過去の背景、判断軸、制約はAIへ渡せる。

しかし、今回その変更を行うか、どの方針を選ぶかは、その時点の状況によって変わる。AIは材料を整理・提示し、人間が内容と現在の条件を確認して最終決定する。

QAによる参照支援を、変更の自動承認にはつなげなかった。

一回の調査を、後続の保守へ使える知識に変えた

既存仕様書だけでは説明できなかった処理と依存関係を、確認・参照できる情報へ整理した。調査結果をその場限りにせず、人向け資料と検索用Knowledgeとして残し、仕様確認、QA、継続的な保守へ再利用した。

詳細章では、コードの調査、処理フローの復元、QAの評価、Knowledgeの修正と更新を扱う。

ここで示す到達点は、システムを全面刷新したことではなく、使い続けるシステムについて、人間が理解・変更を検討できる材料を再構築したことである。

この事例から得たこと

このシステムでは、古さだけでなく、現行仕様へ到達しにくいことが保守を難しくしていた。資料の有無を確認するだけでは足りず、コード・操作・動作をつないで説明できる状態が必要だった。

また、知識を残す形式は一つに固定できなかった。人が全体を理解する図と、AIが必要な根拠を検索する文書は用途が異なる。ただし、どちらも同じ現行仕様を表していなければならない。

判断材料をKnowledge化することは、最終決定を自動化することでもない。背景と制約を参照できるようにしても、変更の採否は現在の状況を踏まえて人間が決める。この境界が、知識の再利用と判断責任を両立させた。