AIコーディングエージェントに古い業務ロジックの削除やリファクタリングを任せて、本番障害を経験したことはないでしょうか。この記事は、レガシーコードの改修にAI支援ツールを使い始めたエンジニアやテックリードに向けて、見落としやすい落とし穴を整理します。
結論から言うと、AIはコードの「差分」は正確に読めても、その差分が生まれた「経緯」までは読めません。この非対称性が、一見クリーンなプルリクエストの裏で事故を起こす原因になります。
何が起きるか
典型的な例を挙げます。以下のような条件分岐がコード中に残っていたとします。
if (user.isLegacy && !featureEnabled) {
return fallback();
}一見すると、使われていない古い分岐に見えます。AIコーディングエージェント（自然言語の指示からコード変更を提案するAIツール）にレビューさせると、「死んだコードの可能性がある」として削除を提案してきます。
テストは通り、プルリクエスト（変更内容をレビューして取り込むためのGitの仕組み、PRと略される）も差分が小さくきれいに見えます。マージして数時間後、特定の顧客セグメントだけで本番障害が発生する、というパターンです。
この分岐は、実は3年前に発生した障害の再発防止として追加されたものだったとします。当時の経緯はコードのコメントには残っておらず、担当したエンジニアはすでに退職しています。影響範囲は、そのコードが呼ばれる決済・注文・会員管理など複数のサービスに及ぶことがあります。
なぜ起きるか
原因を分解すると、Gitというツール自体の性質に行き着きます。Gitは「何が変わったか」「誰が変えたか」「いつ変えたか」を正確に記録します。バージョン管理システムとしては十分な機能です。
しかし業務システムの保守で本当に必要な問いは別のところにあります。「なぜ変更されたのか」「何の問題を解決したのか」「これに依存しているものは何か」「過去に同じ箇所で障害が起きたことはあるか」。こうした問いにGitの標準機能だけでは答えられません。
この情報は失われているわけではなく、実際には存在しています。ただし、Issue管理ツール、PRのレビューコメント、障害対応記録（ポストモーテム）、Slackの会話、退職者の頭の中に分散しています。いわば「エンジニアリングの知識グラフ」が組織の中に暗黙的に存在しているのに、誰もそれをグラフとして扱っていない状態です。
具体的には、Issueが解決されPRが作られ、PRがコードを変更し、コードがサービスに依存し、サービスが障害の影響を受け、障害が修正につながり、修正を誰かのエンジニアが担当する、という一連のつながりです。ノード（要素）そのものよりも、このつながり（エッジ）にこそ価値があります。
通常のコード検索ツールは「このファイルはどこからimportされているか」までは教えてくれます。しかし「このファイルはどのPRで、どの障害の後に、誰のレビューを経て変更されたか」までは追えません。AIエージェントに渡されるコンテキストが前者止まりであれば、提案の質もそこで頭打ちになります。
自分のプロジェクトが該当するか確認する方法
次の観点で、自分のコードベースがこのリスクを抱えているか確認できます。
- コミットメッセージに「Issue番号」や「なぜ」の説明があるか。
git log --oneline -20で直近の履歴を見て、メッセージが「fix bug」のような短い記述ばかりでないか確認する - PRのテンプレートに「背景」「関連Issue」欄があるか。GitHubやGitLabのPR説明が空欄のまま統合されていないか、直近10件をざっと見る
- 障害対応記録（ポストモーテム）が、原因となったコードのファイルパスやPR番号にリンクされているか
git blameで古いコードの最終変更者を調べたとき、その担当者がまだ在籍しているか。組織の在籍者名簿と照合する- AIコーディングエージェントに渡すコンテキストが、ソースコードのみか、それともIssueやPRの説明文も含んでいるかをツールの設定で確認する
これらのうち複数が「いいえ」であれば、コードの経緯が分散して失われつつあるサインです。特に稼働年数が長い業務システムや、担当者の入れ替わりが多いチームほど該当しやすい状態です。
対策の手順
完全な知識グラフ基盤を新規構築する必要はありません。既存の運用に手を加えるだけで、段階的にリスクを下げられます。
手順1: コミットメッセージとPR説明にIssue番号を必須化する
コミットメッセージの先頭にIssue番号を含めるルールを設定します。GitHubであれば Fixes #421 のような記法でPRとIssueが自動的にリンクされます。これだけで、あとから「このコードはどの問題の対応か」を逆引きできるようになります。
手順2: 障害対応記録に該当ファイル・PR番号を明記する
ポストモーテムのテンプレートに「影響を受けたファイル」「関連PR」の項目を追加します。障害番号とコードの対応関係が残っていれば、次に同じファイルを触る人が過去の経緯にたどり着けます。
手順3: AIエージェントに渡すコンテキストを広げる
AIコーディングエージェントにコードの削除や変更を判断させる際、ソースファイルだけでなく関連するIssueやPRの説明文、可能であれば障害対応記録の抜粋も一緒にプロンプトへ含めます。同じモデルでも、渡す情報が変わるだけで判断の質が変わります。ソースコードのみを渡した場合は「削除しても問題なさそうです」という表面的な返答になりがちですが、経緯を含めると「過去の障害対応で追加された可能性があるため、関連Issueを確認してから判断すべき」という慎重な回答に変わります。
手順4: リスクの高いファイルにコメントで経緯を残す
全てのコードに経緯を書き残すのは現実的ではありません。過去に障害の原因になった箇所、複数回修正されている箇所に絞って、コード直前にIssue番号や背景を1〜2行のコメントで残します。git log --follow -- path/to/file でそのファイルの変更頻度が高いかどうかを事前に確認すると、優先順位をつけやすくなります。
手順5: レビュー時に「なぜ存在するか分からないコード」への削除提案は一旦保留するルールを作る
AIによる削除提案であっても、そのコードの追加理由がPRやIssueで確認できない場合は、即座にマージせず一次保留にするレビュー基準を設けます。人間のレビュアーが最終判断を担う運用にしておくことで、事故を未然に防げます。
まとめ
AIコーディングエージェントは差分を作ることには長けていますが、差分の背景にある意思決定までは自動で読み取れません。特に長年運用されている業務システムでは、この差分に注意が必要です。
今日から確認できることとして、まずは git log --oneline -20 で直近のコミットメッセージにIssue番号があるかを見てみてください。次に、PRテンプレートに背景欄があるかどうかもチェックしておくとよいでしょう。
コードの経緯を記録に残す運用を少しずつ整えることが、AI支援開発の恩恵を安全に受け取るための土台になります。