レガシーコードをAIで保守するとき、最初にぶつかる壁

レガシーコードの保守をAIコーディングで効率化したい。そう考えてコードベースをAIエージェントに読ませたとき、最初にぶつかる壁があります。

「なぜこの実装になっているのか、分からない」

人間のチームには「覚えている人」がいた

従来の開発チームでは、この問題はしばしば属人的に解決されてきました。「この処理、なんでString返してるんですか？」と聞けば、古参のメンバーが「ああ、それは外部の販売管理システムがSOAPでString以外受け付けないからだよ。2019年から技術的負債として認識はしてる」と答えてくれる。

ADR（Architecture Decision Record）を残す文化があるチームなら、記録から設計判断の背景を辿れる場合もあります。しかし現実には、ADRの運用を継続できているチームは多くありません。人間にとってのADRは記録コストが高く、運用が形骸化しやすいという構造的な問題を抱えています。

属人知識に頼るにせよ、ADRに頼るにせよ、設計意図が「どこかに存在する」ことが前提でした。しかしAIエージェントには、チームの記憶も暗黙知もありません。渡されたコードとドキュメントが世界のすべてです。

仕様書に残るのは「How」だけ

ドキュメントがあれば解決するかというと、話はそう単純ではありません。

仕様書やAPI定義書に書かれているのは「何をどう実装したか」というHowです。「戻り値はString型」「引数はカンマ区切りの文字列」といった記述は実装仕様を伝えますが、「なぜString型なのか」「なぜカンマ区切りなのか」という設計判断の背景は記載されません。

AIエージェントはHowの情報だけでコードを読み解こうとします。変数名やコメントから文脈を推測しますが、コメントが実装と乖離しているケースや、命名が歴史的経緯で不自然になっているケースでは、AIは誤った前提でコードを解釈してしまいます。嘘をついているコメントを、AIは嘘だと見抜けません。

Whyの手がかりはどこにあるか

では、失われた設計意図をどう掘り起こすのか。レガシーコードにおけるWhyの手がかりは、意外な場所に散在しています。

IssueトラッカーとフィックスPRは、有力な情報源です。「なぜこの修正が必要になったのか」「どんな代替案が検討されたのか」がディスカッションに残っていることがあります。コミットメッセージが「fix」の一言でも、紐づくIssueには判断の経緯が記録されている場合があります。

コメントアウトされた旧コードやTODOコメントも手がかりになります。「// 旧バッチシステムとの互換性のため」「// TODO: List\への移行予定」といった断片的なメモが、設計判断の痕跡を伝えてくれることがあります。

ただし、これらの情報は散在しており、体系的に検索することが難しいのが実情です。人間であれば文脈をつなぎ合わせて推測できますが、AIエージェントにコードベースを渡しただけでは、点と点がつながりません。

設計意図を「検索可能」にする

sqlewは、こうした設計判断の背景を構造化して蓄積し、AIエージェントがMCP経由で「なぜこの実装なのか？」を検索できるようにするツールです。

たとえば、レガシーコードの保守を始める際に、Issueやコメントから掘り起こしたWhyをsqlewに登録しておく。AIエージェントがコードを読んで「この戻り値の型が不自然だ」と感じたとき、sqlewを検索すれば「外部システムとのインターフェース制約による設計判断であり、2019年から技術的負債として認識されている」という背景に即座にたどり着けます。

git blameでは得られない設計意図の検索。コミットメッセージが「fix」でも、AIが判断の経緯を参照できる仕組み。レガシーコードの保守こそ、Whyの永続化が最も価値を発揮する場面だと考えています。