AIコーディング
AIを使ってレガシーソフトウェアを文書化する方法
コードと運用上の根拠からAIでレガシーソフトウェアを文書化し、システム構成、データの流れ、暗黙の業務ルール、依存関係、運用手順を推測に頼らず整理する実践的な手順です。
レガシーソフトウェアの実際の動作は、コード、データベースの構造、処理、設定、デプロイ用スクリプト、問い合わせ対応のノウハウ、運用担当者の記憶に分散しています。そのため、一般的な構成図だけでは不十分です。システムが何を行い、重要なルールがどこにあり、データがどう流れ、どこで障害が起こり、変更をどう安全に検証できるかを示す必要があります。
AIコーディングツールは大規模なリポジトリの横断調査を効率化できますが、もっともらしい誤った説明を生成することもあります。重要な記述は、コード、データベースの構造定義、設定、監視データ、または有識者への確認結果のいずれかで裏付けます。
文書の目的を決める
誰が読み、どのような意思決定に役立てる文書なのかを決めます。新しく参加した技術者にはシステムの案内図、運用担当者にはリリース、監視、復旧、上位担当への連絡手順、移行チームにはシステムの境界、データの管理責任、互換性の制約、暗黙の業務ルールが必要です。
最初の成果物は、重要な業務フロー1つとその依存関係など、範囲を限定します。システム全体を一度に扱おうとすると、内容が浅く、すぐに古くなる文書になりがちです。
秘密情報と本番データを守る
対象リポジトリの利用が認められたAI環境を使います。認証情報、秘密鍵、本番環境から出力したデータ、個人情報、顧客から受信したデータ、機密ログは除外します。調査段階では読み取り専用とし、本番環境への接続、依存パッケージのインストール、破壊的なコマンドの実行、名前だけに基づく動作の推測を禁止します。
根拠付きシステム一覧を作る
リポジトリの作業手順、パッケージや配備の定義ファイル、経路定義、実行開始点、データベースの構造定義と変更用ファイル、サービス、処理、外部連携用のクライアント、テスト、デプロイ用ファイル、運用スクリプトを調べます。連携関係を説明する前に、まず構成要素を特定します。
次の英語のプロンプトを使います。
Act as a software archaeologist. Inspect the supplied repository evidence and create a system inventory covering entry points, services, data stores, queues, scheduled jobs, external integrations, authentication boundaries, configuration, deployment artifacts, and tests. For every statement, cite the file, symbol, schema, or command that supports it. Mark anything not proven by the repository as unknown. Do not change code.
実際にシステムを運用したエンジニアに一覧を確認してもらい、名称が変わったサービス、廃止されたモジュール、自動生成ファイル、特定の環境でしか使われない処理経路を整理します。
構成と責任境界を整理する
利用者、レガシーシステム、外部システム、主要なデータ保存先の全体像を描き、次にアプリケーション、API、バックグラウンド処理を担うサービス、処理待ちの仕組み、定期実行処理、データベースを示します。図は継続的に更新できる程度の分かりやすさに保ちます。
各構成要素について、役割、担当チーム、実行環境、配備単位、入力元、依存先、データ区分、稼働状態を判断する指標、リポジトリ内の場所を記録します。担当が不明な場合は、最後にファイルを変更した人へ勝手に割り当てず、担当者が未定であることを明記します。
重要な業務フローを追跡する
アカウント作成、受注処理、請求、利用権限の変更、返金、データの取り込み、月末処理など、顧客、収益、法令遵守、運用への影響が大きい業務フローを選びます。開始のきっかけから最終状態まで追跡します。
Trace this business workflow through the legacy system: [workflow]. Start at the user or system trigger and follow UI, API, validation, service logic, database reads and writes, background jobs, integrations, retries, and final user-visible state. List the exact files or symbols at every step, identify hidden business rules, and flag branches that require runtime verification.
テスト、条件を限定したローカル実行、検証環境の監視データ、運用担当者による手順確認で裏付けます。コードを読むだけでは、機能の有効・無効を切り替える設定、実行時の設定、データベースのトリガー、外部サービスからの応答通知、手動で起動する処理を把握できない場合があります。
暗黙の業務ルールを抽出する
業務ルールは、条件分岐、状態遷移、入力検証メッセージ、SQLの抽出条件、定期実行の設定、表計算ファイルを介した引き継ぎ、問い合わせ対応手順などに隠れています。各ルールについて、固定ID、平易な説明、根拠となる場所、対象の業務フロー、担当者、例外、テスト範囲、最終確認日を記録します。
文書を分かりやすく見せるために、複雑なルールを勝手に単純化してはいけません。システムの現在の動作と、関係者が本来期待している動作を分けて記述します。
データモデルとデータの流れを記録する
主要なデータ対象、識別子、関係、状態の推移、保持期間、正本となるシステムを整理します。重要なデータ項目がどこで作成、変換、検証、保存、外部提供、削除されるかを追い、動作に影響するトリガー、ビュー、キャッシュ、検索用索引、外部出力も含めます。
実際の顧客データではなく、代表例となる構造定義を使います。日時、通貨、タイムゾーン、値がない状態、過去の履歴データが、それぞれ特別な意味を持たないかも確認します。こうした細部は、移行時の不具合につながりやすいためです。
連携と失敗動作を記録する
外部連携先ごとに、機密値を含めない認証方式、要求と応答の形式、応答待ち時間、再試行方針、冪等性の保証、利用回数の上限、Webhookの検証方法、データの照合方法、障害対応の担当者を記録します。利用者にすぐ見える障害と、後から運用担当者が処理する障害を区別します。
外部呼び出しは成功したのにローカルへの書き込みが失敗する経路と、その逆の経路をAIに探させ、コードとテストで確認します。冪等性が根拠によって確認できない限り、再試行を安全だとみなしてはいけません。
デプロイと運用手順書を作る
環境の作成、設定値の投入、リリースの配備、データベース変更の適用順序、稼働確認、異常通知の連絡先、切り戻し、または追加修正による復旧の手順を記録します。前提条件、コマンド、期待される出力、中止条件、役割ごとの連絡先を含めます。
非本番環境で手順書を実際に試します。一度も実行されていない手順書は、正式な運用手順ではなく草稿にすぎません。確認日と、確認した担当者またはチームも記録します。
新任者向けの習得手順を作る
システムの全体像、用語集、ローカル環境の準備、読み取り専用での操作確認、重要な業務フロー、よくある障害、安全な小規模変更の順に学べるようにします。同じ説明を複数のページへ複製せず、正本となるページへリンクします。
どの種類の情報をどのページが管理するかを文書の索引にまとめ、README、社内Wiki、運用手順書、移行計画の間で内容が食い違わないようにします。
すべての記述を根拠と照合する
最後にAIを使って、記述の矛盾や情報の古さを確認します。
Review this legacy system documentation against the supplied code and operational evidence. Find unsupported claims, stale names, missing failure paths, undocumented dependencies, secrets or personal data that should be removed, and instructions that cannot be reproduced. Return findings by severity with the evidence and the smallest documentation correction. Do not edit code.
重要な記述、リンク、コード上の識別子、コマンド、図を人手で抜き取り確認します。情報が古くなると運用上の危険が生じるページには、担当者と確認日を付けます。
実践例
請求サービスの置き換えを計画したチームの旧文書には、「夜間の定期処理で請求書を作成する」としか書かれていませんでした。リポジトリを調べると、処理待ちの仕組みから即時に反映される利用量調整、管理画面から作成する貸方伝票、状態変更を台帳テーブルへ複製するデータベースのトリガーも見つかりました。
4つの動作をすべて根拠付きで記録したため、移行チームは目につきやすい夜間処理だけを移行し、利用量の調整や台帳の履歴を失う事態を避けられました。AIは調査を速めましたが、実際に使われている経路の判断にはテストと運用担当者の確認が必要でした。
品質チェックリスト
- 重要な記述が、コード、データベースの構造定義、設定、監視データ、または確認済みの有識者情報で裏付けられている。
- 現在の動作と将来の目標が分けて記録されている。
- 重要な業務フローに、成功、失敗、再試行、復旧の各経路が含まれている。
- データの流れに、正本となるシステムと変換箇所が示されている。
- 外部連携の文書に、冪等性とデータの照合方法が記載されている。
- 運用手順書に、期待される出力、中止条件、確認日がある。
- 認証情報や個人情報が含まれていない。
- 各ページに担当者と現実的な更新方針が定められている。
よくある失敗
- リポジトリの根拠を示さず、AIにシステム構成の要約を求める
- ファイル名や関数名を実行時の動作の証拠とみなす
- 正常に完了する経路だけを記録する
- 本番環境の記録や認証情報をAIへの入力に含める
- データベースのトリガー、処理待ちの仕組み、機能の切替設定、手作業を見落とす
- 複雑な現行ルールを文書上で勝手に単純化する
- 誰も管理しない巨大な社内Wikiを生成する
- 移行に関する提案を、現状を示す事実の文書に混ぜる
FAQ
**AIでコードベース全体を自動的に文書化できますか？** 最初のシステム一覧は作れますが、対象範囲、根拠の要件、人手による検証を定めずに大量生成した文書は信頼できません。
**文書はコードと同じ場所に置くべきですか？** 安定した技術仕様や運用手順書は、バージョン管理の対象にすると更新を追跡しやすくなります。業務上の背景は別の場所でも構いません。重要なのは、情報の種類ごとに正本となる場所と担当者を明確にすることです。
**どのくらいの頻度で確認すべきですか？** 関連するコード、基盤、外部連携、運用手順が変わったときに見直します。重要な運用手順書と担当者情報は、定期的にも確認します。
**同じ文書をシステム移行にも使えますか？** はい。まず根拠に基づく現状の記録を確定し、移行後の目標構成、差分分析、移行計画を別に作成すれば活用できます。