最初に復元するのは仕様書ではなく判断できる状態
ブラックボックス化したシステムとは、業務では使われているものの、どの処理がどのデータや外部サービスに依存しているかを説明できない状態です。古い仕様書が残っていても、現在の動作と一致するとは限りません。
この状態で最初から作り直すと、コードに埋もれた例外処理や、担当者だけが知る運用を落とします。先に必要なのは、立派な仕様書ではありません。対象業務の入力、処理、出力、例外、外部連携を、根拠と一緒に説明できる状態です。
AIは、この調査を速める道具になります。GitHubの公式ガイドでも、コードベースの構造、入口、データの流れを調べる使い方が紹介されています。ただし、AIが返した説明は調査仮説であり、そのまま現行仕様にはできません。
仕様は4つの証拠を突き合わせて復元する
コードだけを読んでも、実際の運用は復元できません。次の4種類を突き合わせ、同じ挙動を示しているか確認します。
| 証拠 | 確認できること | 見落としやすい点 |
|---|---|---|
| ソースコード、設定、DBスキーマ | 処理分岐、データ構造、外部接続の候補 | 本番だけの設定、未使用コード |
| 実行ログ、通信、ジョブの実行結果 | 実際に通る処理、接続先、実行頻度 | 月次・年次など低頻度の処理 |
| 操作手順、帳票、担当者への確認 | 手作業、例外対応、業務上の正しい結果 | 個人の記憶と現在の動作のずれ |
| 現行動作を記録するテスト | 入力に対する出力と、変更前後の差 | 正常系だけでは残る境界値や異常系 |
AWSの詳細アセスメント指針も、既存文書や組織内の知識を鵜呑みにせず、取得したデータで検証することを勧めています。構成要素に加え、社内外のシステム、データ、運用周期まで依存関係として記録する考え方です。
4種類の証拠が一致しない箇所は、都合よく補完せず「未確認」とします。この未確認事項が、試作の対象や移行順を決める材料になります。
AIに頼むのは答えではなく探索の下書き
AIには、広いコードから確認候補を短時間で絞る作業を任せます。採用判断は人が行い、根拠をファイル、ログ、実行結果へ戻します。
| AIに任せる作業 | 人が確認すること |
|---|---|
| 入口、呼び出し関係、データフローの候補 | 実際に使われる経路か、業務上の意味が正しいか |
| API、DB、バッチ、ライブラリの洗い出し | 本番設定と一致するか、契約や運用制約があるか |
| テスト観点と確認用コードの下書き | 期待結果が現行業務と一致するか、漏れがないか |
| 小さな代替案や試作コード | セキュリティ、受入基準、切り戻し方法が妥当か |
GitHubもCopilotのベストプラクティスで、生成されたコードを理解し、機能、安全性、保守性をレビューしたうえで、自動テストや解析ツールで検証するよう案内しています。これはコード生成だけでなく、AIが作った仕様説明にも当てはまります。
調査は変更を止めた基準点から始める
調査中に対象が変わり続けると、説明と実機のずれを追えません。まず、どの時点のシステムを調べるかを固定します。
- ソースコードのコミット、ランタイム、設定項目、DBスキーマ、定期ジョブを記録する。
- 売上集計や申請承認など、調べる業務フローを一つに絞る。
- 入口から出力までをAIで追い、根拠となるファイルやログを紐づける。
- 同じ入力を現行環境で実行し、出力、更新データ、通知を記録する。
- 確認できた事実、仮説、未確認事項を分け、業務担当者とレビューする。
本番の秘密情報や個人情報を、そのまま外部のAIサービスへ渡してはいけません。利用する環境の契約、データ利用条件、アクセス範囲を確認し、必要なら値を伏せた調査用データを用意します。
調査票は、文章だけでなく次のような行単位にすると更新しやすくなります。
| IDと確認項目 | 調査記録 |
|---|---|
| B-01 承認後に誰へ通知されるか | AIの仮説: 申請者と管理者へメール送信 根拠: 関数、設定、メールログ 実機確認: 未実施 判定: 未確認 |
| B-02 締め日を過ぎた申請を扱えるか | AIの仮説: 管理者だけが例外登録できる 根拠: 分岐、権限表、操作記録 実機確認: 一致 判定: 確認済 |
AIの説明だけで「確認済」にしないことが重要です。根拠をたどれない説明は、調査の入口にはなっても仕様にはなりません。
調査後に残す成果物は5つに絞る
調査の目的を文書の量にすると、刷新判断に使われない資料が増えます。最低限、次の5つを残します。
- 現行構成一覧: ランタイム、DB、外部API、バッチ、配備方法
- 依存関係図: 画面、処理、データ、社内外サービスの接続
- 挙動確認表: 入力、出力、例外、証拠、確認状態
- 未確認事項と判断記録: 影響、確認担当、期限、採否の理由
- 現行動作テスト: 変更前後を同じ条件で比較できる確認手順
完全な仕様書ができるまで待つ必要はありません。対象業務について、どこまで確認でき、何が分からず、変更時にどこへ影響するかを説明できれば、次の判断へ進めます。
小さな試作は書き込みの少ない境界から始める
最初の試作には、業務上の境界が明確で、現行との比較ができ、問題があれば止められる範囲を選びます。たとえば、既存データを読む社内レポート、検索画面、入力ファイルの事前検査などです。認証、決済、会計データの更新を最初の対象にする必要はありません。
Microsoftのモダナイゼーション計画でも、複雑なシステムを一度に刷新せず、小さく実行してテストできる段階へ分け、低リスクで価値のある変更から始めるよう示しています。
試作の完了条件には「動いた」だけでなく、現行結果との差、対象外の処理、停止方法、元へ戻す手順を入れます。試作で新たな依存関係が見つかったら、仕様復元の記録へ戻し、次の範囲を調整します。
この記事で参照した外部資料は、2026年7月14日に確認しました。
このサイトの移行でも画面だけを仕様にしなかった
このサイトの移行でも、ページ本文と見た目だけでなく、旧URL、問い合わせ通知、アクセス解析、リダイレクト、SEO補助ファイルを別々の確認項目として扱っています。画面が表示されるだけでは、既存システムの移行は完了しないためです。
刷新計画全体の確認点は、古いシステムをAIで刷新する前に確認するべきことで整理しています。AIが作ったコードや説明を人が確認する理由は、AIが作ったコードを人がレビューする理由もご覧ください。
コード、構成、運用のどこから調べるべきか分からない段階でも構いません。私たちは現行調査、仕様復元、小さな試作、移行計画を一続きで整理します。既存システム刷新サービスの内容をご確認のうえ、対象システムの状況をお問い合わせからお聞かせください。