仕様書は調査の入口ではなく、調査の結果としてつくるものです。まず「何が事実として確認でき、何が推測で、何が未確認か」を分け、読み取り中心の確認から始めます。全面改修や環境移行を決めるのは、そのあとで構いません。
1. 動いている画面と業務から事実を集める
最初に、利用者が日常的に行っている操作を聞きます。ログインから始めて、入力、検索、承認、通知、出力、終了までを実際の順番でたどります。画面の名前やURLだけでなく、誰が操作し、どの情報を見て、どんな判断をしているかを記録してください。ここで集まるのは、コードを読む前に確認できる、いちばん確かな事実です。
この段階で、コードの意図を推測してはいけません。現場の人が「このボタンは使わない」と言っていても、別の役割の人が使っている可能性があります。利用者の役割ごとに、通常の流れと例外の流れを分けて聞いておくと、あとでテストの観点としてそのまま使えます。
2. 実行環境とデータの地図を作る
次に、どこでシステムが動き、どのデータがどこに保存され、何とつながっているかを確認します。順番を決めずに調べ始めると、影響範囲の分からない場所へ先に触れてしまいます。次の順序で進めると、本番を止めるリスクを抑えられます。
- 01
本番・検証・開発の境界と管理権限。どの環境が利用者に見えていて、誰がログインできるかを先に確定します。
残す資料環境一覧、権限一覧
- 02
画面から行われる入力と出力。1で聞いた業務の流れを、画面一覧と対応させます。
残す資料業務フロー、画面一覧
- 03
コードの入口、主要な処理、設定。構成図と、処理の説明を文章で残します。
残す資料構成図、処理の説明
- 04
データの項目、関係、保持と削除。個人情報の有無、バックアップ、復元手順まで確認します。
残す資料データ項目表、移行・バックアップ方針
- 05
外部連携、定期処理、通知。認証、決済、メールなど、止まると業務が滞るものを一覧にします。
残す資料連携一覧、失敗時の手順
- 06
ログ、監視、障害対応。既知の課題と、これまでの対応方法を記録します。
残す資料運用手順、既知の課題
いずれも、確認日と確認方法を書き添えます。資料に書かれていたこと、画面で再現したこと、コードから読み取ったことを同じ欄に混ぜないでください。出所が分かれていれば、あとから誰かが検証し直せます。
3. コードは「全部読む」より入口から追う
コードを最初からすべて読もうとすると、時間がかかるうえに業務との対応を見失います。利用者がよく使う画面か、止まると影響が大きい処理をひとつ選び、画面の入口、権限確認、データの読み書き、外部連携、エラー処理の順に追います。ひとつの流れが分かったら、似ている処理と違う処理を比べていくほうが早く全体像に届きます。
調査中に出てきた仮説には「要確認」と印を付けます。古い設定、使われていない機能、例外的な管理者権限などは、コードだけで判断しないことが大切です。仕様書がないからといって、コードに書かれた動作がそのまま正しい業務とは限りません。現場での確認とテストを通して、これから守るべき動作を合意します。
4. 調査結果を、次の改修に使える資料にする
調査資料は、読み物ではなく作業に使える形にします。最低限、次の4点がそろっていれば、別の担当者や別の会社でも引き継げます。
- システム全体の構成図と、環境ごとの違い
- 主要な業務フローと、利用者・権限の対応表
- データ、外部連携、定期処理、バックアップの一覧
- 既知の課題、リスク、優先順位、次に確認すること
ここまで来ると、「触ると壊れそう」という不安を、具体的な調査課題に分けられます。改修は、影響範囲が小さく、利用者が確認しやすいものから始めます。変更の前後でテストと戻し方を記録し、資料も同時に更新してください。引き継ぎの依頼そのものを整理したいときは、他社開発システムを引き継ぐときのチェックリストに、権限・コード・データ・運用・契約の確認項目をまとめています。
5. AIを使うときに、人が判断すること
コードの検索や資料の下書きにAIを使うことは、調査の助けになります。ただし、AIが作った説明を、そのまま正しい仕様として扱ってはいけません。個人情報や認証情報を含むデータを外部へ渡さないこと、出力をコードと画面で照合すること、権限・データ・エラー処理の最終判断を人が行うことが必要です。当社のAI駆動開発の実践でも、要件の理解、設計の判断、コードレビュー、テストの観点はエンジニアが担うものとして分けています。
いきなり全面改修を決めない
仕様書がない状態で、作り直しや環境移行を先に決めないでください。まず、現状調査の範囲、読み取りだけで触る場所、現時点では確認できないリスク、資料の納品形式を合意します。動いているシステムは止めず、可能なら検証環境で再現し、必要な秘密保持契約とアクセス権限を整えてから調査に入ります。
DEPARTUREの既存システムの引き継ぎ・継続改修では、コードと実際に動いている画面から調査し、ドキュメント整備、引き継ぎ、継続改修までを段階的に支援しています。調査のあと継続して運用する例としては、競技者管理システムの保守・機能追加の実績を公開しています。分かっている資料が少なくても、現在地の確認からご相談いただけます。