既存のコードベースにAIツールを導入するときの進め方｜調査から小さな改修まで

長く運用してきたシステムにAIコーディングツールを入れるときは、新しく作るシステムより心配が大きくなりがちです。書いた人がすでにいない、テストが少ない、古いライブラリを使っている。こうした事情があると、変更の影響を読みにくいからです。

一方で、既存のコードベースだからこそAIが役立つ場面もあります。誰も全体を把握していないコードを読み解くときや、文書が残っていない処理の説明を作るときです。

この記事では、既存のコードベースにAIツールを導入するとき、どの順番で進めると安全かを説明します。ツールの機能や料金は製品によって異なり、変わることもあります。導入時は各製品の公式情報を確認してください。

最初はコードを変えない作業から始める

既存のコードベースでは、いきなりコードの変更を任せるのは避けたほうが無難です。最初は、コードを読み、説明を作る作業から始めましょう。

たとえば、ディレクトリごとの役割をまとめる作業や、主要な処理の流れを説明する作業があります。使われていないように見える関数を一覧にするのもよいでしょう。どれもコードを変えないため、AIの説明が間違っていても直接の影響はありません。

AIの説明は、既存のコードをよく知るメンバーに確認してもらいます。間違いが多い部分は、コードの書き方が分かりにくいか、古いコメントが残っている部分であることが多いものです。そうした部分は、後の改修で優先して手を入れる候補になります。

作った説明は、人が読める文書として残しておきましょう。AIのためだけでなく、新しく加わるメンバーにも役立ちます。新メンバー向けの使い方は、開発チームの新メンバーの立ち上がりにAIを使うで取り上げました。

調査の作業は、既存メンバーにとってもAIツールに慣れる機会になります。コードを変えない作業であれば、使い方を試しながら、どの程度の説明が得られるかを確かめられるでしょう。チームで使い方の感触をつかんでから変更の作業に進むと、ルールも決めやすくなります。

変更を任せる前にテストを用意する

コードを変える段階に進む前に、今の動きを確かめる手段を用意します。既存のシステムでは、テストが少ないか、ほとんどない場合もあるでしょう。

テストがない部分を変えると、変更後に動きが変わったかどうかを確かめられません。そこで、変更したい部分について、今の動きをそのまま記録するテストを先に作ります。この種のテストは、正しい仕様を確かめるものとは少し性格が違います。今と同じ動きを保てているかを確かめるためのものです。

テストの作成にもAIを使えます。ただし、AIが作るテストは、今のコードの動きに合わせて書かれます。今の動きに不具合が含まれていれば、その不具合も正しい動きとして記録されてしまうでしょう。テストの内容は人が読み、意図した動きかどうかを確認してください。テストの作成で気をつけたい点は、テストコードの作成にAIを使うときの注意点にまとめています。

テストをどこまで用意するかは、変更したい範囲に合わせて決めます。システム全体のテストを一度にそろえようとすると、改修に進むまでに時間がかかりすぎるからです。触る予定の部分から順に用意していくと、作業を続けやすいでしょう。

小さな改修から試す

テストが用意できたら、小さな改修から任せます。変数名の整理や重複したコードのまとめ、古い書き方の置き換えなど、動きを変えない改修が向いています。

一度に頼む範囲は小さくしましょう。複数のファイルにまたがる大きな変更を一度に頼むと、レビューの負担が大きくなります。問題があったときに原因を探しにくくなる点も困りものです。一つの変更で一つの目的、を基本にします。

改修の結果は、通常のレビューの流れに乗せます。動きを変えないはずの改修で、テストの結果が変わった場合は、その理由を必ず確認してください。

改修を重ねたら、AIに任せた作業のうち、手直しが少なかったものと多かったものを振り返ります。手直しが少なかった種類の作業から、任せる範囲を少しずつ広げていくと安全です。

任せない範囲を決める

既存のシステムには、影響が大きく、慎重に扱うべき部分があります。そうした部分は、AIに任せない範囲として事前に決めておきます。

表は一例です。何を任せない範囲にするかは、システムの性質や過去の障害の経験によって変わります。範囲を決めたら、チームの運用ルールやリポジトリの指示書に書いておきましょう。人によって判断が変わるのを防げます。

古い技術が使われている場合

古い言語のバージョンやライブラリが使われている場合、AIが新しい書き方でコードを作ってしまうことがあります。動作する環境で使えない書き方が混ざると、ビルドや実行の段階で問題が出るでしょう。

使っている言語やライブラリのバージョンは、指示書や依頼文に明記しておきます。それでも新しい書き方が混ざることはあるため、ビルドとテストで確かめる手順は省けません。

古い技術について説明を求めるときも、AIの回答は公式の文書や社内に残る資料と照らし合わせてください。提供が終わった技術では、手元の資料のほうが当時の仕様を正しく残している場合があります。

バージョンを上げる作業そのものにAIを使うことも考えられます。ただし、影響が広い作業になりやすいため、計画を立てて段階的に進めるのが安全です。

請求CSVの出力処理を調べる想定例

架空の販売管理システムで、請求CSVの出力処理に重複が多いとします。CSVは別部署の会計システムへ渡しており、処理を書いた担当者は異動済みです。ここでAIに「重複をすべて解消して」と頼むと、列の順番や空欄の扱いまで変わるかもしれません。

最初は変更せず、出力を始める画面や定期処理、データ取得、列の組立て、ファイル保存までを調べます。AIへの依頼は「請求CSVを作る処理の呼び出し順を示し、各段階の根拠ファイルと未確認事項を記載する」とします。得られた説明は、担当者がコードと実行設定を開いて確認します。

コード検索で呼び出し元が見つからない関数も、すぐに削除対象へ入れないでください。定期実行の設定、外部からの呼び出し、文字列で指定する処理などは、通常の関数参照だけでは見つからない場合があります。運用手順や実行履歴も調べ、確認できていない範囲を文書に残します。

変えてはいけない出力を先に記録する

請求CSVの例では、内部の書き方を整理しても、会計システムへ渡す形式は維持する前提とします。確認用には架空の請求データを使い、個人情報や実際の取引金額をAIへ渡さないようにします。

日付、文字コード、改行の形式なども、接続先がどのように読み込むかに関係します。現在の出力と設計資料が違う場合は、今の出力を残すべきか、今回修正するべきかを業務担当者に確認します。AIが「一般的な形式」に直したから正しいとは限りません。

この記録は、現状を保存するための資料です。既知の不具合まで無条件に正しい仕様と扱わず、「互換性のため維持」「今回修正」「未確認」に分けます。不具合修正と内部整理を別の変更にすると、出力が変わった理由を説明しやすくなります。

最初の改修は一つの処理に限定する

確認用の入力と出力をそろえたら、たとえば列を組み立てる一つの関数だけを整理します。関数の名前や引数を外部から使っている場合は、その約束を変えない範囲で進めます。依存ライブラリの更新や保存形式の変更を同時に追加しないことも、依頼に明記します。

改修後は、同じ架空データで生成した結果を比べます。差が出たときは、見た目だけで判断せず、値、順番、空欄の扱いを確認します。意図した差なら課題とテストを更新し、意図しない差なら変更を小さく戻して原因を調べます。

古いシステムでは、手元の新しい環境でテストが通っても、本来の実行環境では動かない場合があります。対応する言語やライブラリの版で確認できたかを報告に含めます。実行環境を再現できていない段階では、動作確認済みとして扱わないようにしましょう。

テストに失敗したら、期待値を直す前に理由を分ける

失敗の原因は、今回の変更、以前からある環境の問題、仕様の認識違いなどに分けます。改修前でも同じテストが失敗するなら、その状態を先に記録します。改修後だけ出る差であれば、変更した処理と対応付けて確認します。

「テストが通るようにして」とだけAIに依頼すると、期待値を書き換えて差を消してしまうことがあります。どの動作を維持するかを改めて伝え、実装と期待値のどちらを変えたのかをレビューしてください。説明のつかない差が残る場合は、調査に戻るほうが、後から影響範囲を探す負担を抑えられます。

まとめ

既存のコードベースにAIツールを導入するときは、コードを変えない調査と説明から始め、テストを用意してから小さな改修に進むと安全です。影響の大きい部分は任せない範囲として事前に決めておきましょう。AIの説明や変更は、コードをよく知るメンバーと確認しながら進めます。

e-Grantsでは、Codex・Claude Code・GitHub Copilotの導入と、チームで使うための運用ルールの整備を支援しています。既存のシステムでの進め方を相談したい場合は、AI開発環境の導入・整備をご覧ください。