Skip to Content
Docs08. コーディングエージェントレガシーコード理解と仕様復元
中級se-practicelegacy-codemodernization更新: 2026-10-04この記事の誤りを報告

この記事の音声は準備中です。

音声の一覧・再生リストへ

レガシーコード理解と仕様復元

この記事の目的

大規模・古いコードベースの保守や再構築で、AI コーディングエージェントコードベースを読み、ファイルを編集し、コマンドを実行して検証するループで開発タスクを遂行する Agent。コード補完と異なり「タスク単位の委任」を受けられる。を構造把握・処理フロー追跡・仕様書起こし・影響調査・モダナイゼーション支援に使い分けられるようになります。あわせて、この領域で最も重要な原則である「現行挙動は観測事実、要件との一致は別に判断し、復元した仕様はドラフト」を保ったまま作業を進める方法と、古い言語・環境への対応度を見極める確認手順を持ち帰れる状態を目指します。

対象読者

  • ドキュメントが失われた・古いコードベースの保守や改修を担当する SE
  • レガシーシステムのモダナイゼーション(段階的移行)を検討していて、AI をどこまで頼れるか見極めたいエンジニア

前提知識

本文

概要: 何に使えて、何を正とするか

レガシーコードの理解は、コードから設計意図を逆向きに読み解く作業(リバースエンジニアリング(reverse engineering))です。エージェントは読解の速度を上げますが、何が起きているかはコード・実入出力で観測し、何が正しいかは要件・契約・既知の不具合に照らして関係者が判断します。

作業エージェントの役割(発散・下書き)何が正か・人が握ること
構造把握・フロー追跡構造の要約・処理フローの説明実コード・入出力で観測事実を確認(要約は仮説)
仕様書起こしコード → 仕様ドラフト現行挙動の説明を復元し、要求仕様との不一致は別に判断
影響調査改修範囲の候補洗い出し影響有無の最終判断
デッドコード・重複発見候補の指摘削除可否の判断(呼び出し実態の確認)
モダナイゼーション移行方針・変換の下書き移行判断・等価性の検証

この表を貫く原則は 1 つ、**「現行挙動は観測事実、生成物は仮説・ドラフト、要求の正当性は別判断」**です。以下、各作業を見ます。

大規模・古いコードベースの理解

まず効くのは、全体像をつかむ発散の使い方です。

  • 構造把握: ディレクトリ構成・モジュール依存・主要な処理の入口を要約させ、コードベースの地図を速く作ります。人が一から読むより、当たりをつけてから深掘りできます
  • 処理フローの追跡: 「この入力がどこを通ってどう処理されるか」を説明させ、フローの下書きを得ます。分岐・例外系の見落としを拾う補助になります
  • 「なぜこうなっているか」の仮説出し: 不可解な実装について、背景の仮説を挙げさせます。ただしこれは仮説であり、実際の経緯(過去の障害対応・業務都合)は履歴や関係者に当たって確かめます
  • 要約は仮説として扱う: エージェントの構造要約は、読み飛ばした分岐や隠れた副作用を含みます。重要な理解は、必ず実コードで裏を取ります

仕様書起こし(コード → 仕様)

ドキュメントが失われたシステムで需要が高いのが、コードから日本語仕様のドラフトを起こす使い方です。

  • 仕様ドラフトの生成: 対象コードを渡し、処理内容・入出力・分岐条件を日本語仕様のドラフトにさせます。白紙から書き起こすより速く進みます
  • 復元仕様は正としない: 生成された仕様は、コードのもっともらしい説明であって、正解ではありません。エージェントは複雑な条件分岐を単純化したり、例外系を落としたりします。「復元仕様=正」とした瞬間に、実挙動とのズレが仕様として固定されます
  • 検証は現行挙動と突き合わせる: 復元仕様は、実際のシステムの入出力・テスト結果と突き合わせて検証します。仕様とコードが食い違ったら、観測した挙動と要求仕様の不一致を記録します。維持すべき仕様か既知・新規の不具合かを関係者が判断し、差分を説明できる状態にします

影響調査

改修時の影響調査(impact analysis) — 変更が波及する範囲の洗い出し — は、レガシーで特に骨の折れる作業です。

  • 改修範囲の候補洗い出し: 「この関数/テーブルを変えたら影響しそうな箇所」を列挙させ、調査の当たりをつけます。呼び出し関係・データの流れの追跡補助になります
  • 候補であって結論ではない: エージェントの洗い出しは見落としも過剰検出もあります。動的な呼び出し(リフレクション・文字列によるディスパッチ・設定駆動)や、コード外の連携(バッチ・DB トリガ・外部システム)は追い切れないことがあります
  • 影響なしの断定を信じない: 「影響ありそうな箇所」の提示には使えますが、「影響なし」の保証には使いません。影響有無の最終判断は、実コードの確認とテストで人が行います

デッドコード・重複の発見

  • 候補の指摘: 使われていなさそうなコード・重複した処理を指摘させ、整理の候補を得ます
  • 「使われていない」の確認が要る: レガシーでは、動的呼び出し・条件付き実行・年次バッチのように低頻度だが生きているコードがあります。エージェントが「デッド」と判断しても、削除前に呼び出し実態(ログ・呼び出し元・運用スケジュール)を人が確認します
  • 重複は統合方針とセットで: 重複の指摘は有用ですが、統合してよいか(片方に固有の分岐がないか)は人が判断します

古い言語・環境への対応度

COBOL・VB・古いメインフレーム資産などでは、モデル・ツールの対応度が成否を分けます。ここは変化が速いため、断定せず確認手順で扱います。

  • 対応度は事前に測る: 対象の言語・方言・環境について、小さな実コードで「正しく読解・変換できるか」を試してから本格投入します。メジャーな言語ほど得意で、方言・独自拡張・環境依存が強いほど精度が落ちます
  • 学習データの薄い領域に注意: 世に出回るコード量が少ない言語・環境は、モデルの理解が浅く、もっともらしい誤りが増えます。「読めているように見えて要点を外す」リスクが高い領域です
  • 確認方法を持つ: 特定の言語対応が必要なら、使うツール・モデルの対応状況を公式情報と実測で確認します(下記 TODO)

モダナイゼーション支援

モダナイゼーション(modernization) — 古い技術資産を新しい基盤へ移す取り組み — でも、エージェントは下書きの道具として効きます。

  • 段階的移行での使いどころ: 一括書き換えではなく、モジュール単位の変換・テスト整備・ドキュメント化を段階的に支援させます。リスクの高い全面置換より、小さく移して検証する進め方に合います
  • 等価性の検証が核: 移行の成否は「新旧で挙動が等価か」で決まります。エージェントの変換は下書きであり、等価性は現行の入出力を基準にした characterization / 回帰テストプロンプト・ツール・モデルの変更で既存の品質が壊れていないかを、評価データセットの再実行と前回比較で検知するテスト。で人が確かめます。これは現行挙動が要件に適合する証明ではありません。既知の不具合を修正する場合は、維持対象から外す承認と要件由来の期待値を別に記録します
  • 移行判断は人: 何をどの順で移すか、そもそも移すべきか(塩漬け・再構築・現状維持の選択)は、業務リスクと投資判断であり人が決めます。エージェントは判断材料の整理を助けるに留めます

実務での注意点

アンチパターン

  • 復元した仕様を「正」として扱う → 単純化・例外系の欠落が仕様として固定される → 現行挙動を観測し、復元仕様と要件の不一致を記録して関係者が判断する
  • 影響調査の「影響なし」を信じる → 動的呼び出し・コード外連携を見落として本番障害になる → 「影響ありそう」の当たり付けに使い、影響なしの判断は人がテストで行う
  • 「デッドコード」を確認せず削除する → 低頻度だが生きているコードを消す → 呼び出し実態(ログ・運用スケジュール)を確認してから削除する
  • レガシー言語の読解を無条件に信頼する → 学習データの薄い言語で要点を外す → 小さな実コードで対応度を実測してから投入する
  • モダナイゼーションで等価性検証を省く → 新旧で挙動がズレたまま移行する → 観測した入出力を期待値にした等価性テストと、要件由来の正当性テストを分ける

チェックリスト

  • 現行挙動の観測事実と要件の正当性を分け、不一致・既知の不具合を判断事項として記録した
  • 復元仕様を実際の入出力・テストで検証している
  • 影響調査を「当たり付け」に使い、影響なしの判断を人がテストで行っている
  • デッドコード削除の前に呼び出し実態を確認している
  • 対象のレガシー言語・環境での読解/変換精度を、小さな実コードで実測した
  • モダナイゼーションで新旧の等価性を、現行挙動を基準にした回帰テストで検証し、要件に基づく修正を別に承認している

関連トピック

参考資料

TODO・未確認事項

本文の未確認事項を参照してください。

テスト工程での活用保守・運用フェーズでの活用