この記事は 株式会社カオナビ Advent Calendar 2025 シリーズ2の16日目の記事です。
はじめに
レガシーシステムの改修やリプレイスにおいて、既存の挙動を正確に把握することは最も重要な課題の一つです。
この課題に取り組むにあたり、AIエージェントの整理能力を借りつつ、自分の目でコードを追い、画面側の挙動も見比べるというハイブリッドな方法を試みました。結果として、この組み合わせが自分にはいちばん進めやすい形でした。
この記事では、その体験をもとに「こうすると整理しやすかった」と感じたポイントを共有します。
なぜこの方法が必要だったのか
レガシーコードを読む中で、特に最初の“全体像をつかむ”部分に課題を感じていました。
- どこを起点に見ればいいのか分かりにくい
- 古い仕様書と現状の挙動が一致しているか判断しづらい（特に非文書化部分）
- コードと画面側の動きのつながりを追いにくい
これらの課題を解決するため、AIエージェントに全体像の整理や情報収集を任せ、人が最終的な検証と判断という、コアな作業に集中できるアプローチが適していると考えました。
AIエージェントはコードの構造を“整理して提示”できる
AIエージェントを使ってコードを見てもらうと、自分では時間がかかりそうな部分を、ある程度まとまった形で示してくれます。
- ファイルがおおまかに何をしていそうか
- 処理の流れがどう組まれているか（例：主要な制御フロー）
- どの関数が中心になっているか
- どんな依存があるか
こうした情報は、全体像をつかむための入口としては非常に助けになります。ただし、AIエージェントは誤った解釈をする可能性があるため、最終的には自分でコードと画面の挙動を見て裏付けを取ることで、より確実な理解につながります。
Tips: これらの情報を得た後、AIエージェントの出力をベースにmermaidなどのツールでフローチャートや依存関係図を作成すると、より素早く全体像を把握できます。
AIエージェントには「推測禁止」を徹底
仕様を文章にまとめていくうえで一番避けたいのは、AIエージェントが推測で情報を補ってしまうパターンです。この推測こそが、リバースエンジニアリングにおける誤解の元凶となり得ます。
そのため、AIエージェントに質問するときは、回答の信頼性を高めるために、毎回つぎの一文を添えるように徹底しました。
推測は禁止。コードから読み取れる事実のみ回答してください。 不明な点は「不明」としてください。
これにより、コードに基づいた情報だけが並び、自分で確認する際も扱いやすくなります。
実務で効果があった5ステップ
AIを「整理役」、人間を「検証・判断役」と明確に分けることで、以下の手順で効率的に進められました。
- 1. AIエージェントに「このファイルは何をしている？」と聞く
- まずざっくり全体の方向性をつかみ、リバースエンジニアリングの起点とします。
- 2. 主要な処理・関数を挙げてもらう
- どこを重点的に見ればいいかの見当をつけ、観察の焦点を絞ります。
- 3. 古い仕様書と食い違いそうな部分だけ質問して深掘り
- 推測禁止の指示を添えて、コードにある事実だけを整理します。
- 4. 実際の画面の挙動を確認
- AIの説明や古い仕様を鵜呑みにせず、chrome-devtools-mcpなどで実際の画面挙動を観察し、コードの実装と照合して検証します。
- 5. 最後に「仕様書風にまとめて」と依頼
- 理解した内容を文章として整理し、最終的な仕様書のアウトプットとして形にします。
🎉 まとめ
AIエージェントを併用してみたところ、レガシーコードの解析が以前より整理しやすく感じました。
- AIエージェントは、複雑なコードの構造や流れをまとめてくれる整理役であり、確認ポイントの見当がつけやすくなる
- 「推測禁止」の指示により、信頼性の高い事実情報だけを抽出できる
- 人間が画面やコードを確認しながら進めることで、最終的な仕様の正確さを確保できる
リプレイスや改修で迷いやすい場面では、AIエージェントを「判断を任せる相手」ではなく、「整理を手伝ってくれる補助役」として使うと、コードの意図やふるまいが格段に見通しやすくなるでしょう。