AIでコードをリファクタリングする方法｜レガシーコードを保守しやすくするプロンプト術

チームに引き継いだコードが読めない、数年前に書いた自分のコードが解読できない——そんな経験はないでしょうか。リファクタリング（コードの内部構造を整理・改善すること）は重要とわかっていても、時間がかかり後回しにしがちな作業です。

この記事では、ChatGPTやClaudeにコードを渡すだけで、リファクタリングと命名改善を効率的に進める方法を解説します。プログラミング経験が浅い方でも使えるプロンプトを完成形で掲載しているので、すぐに試せます。

AIコードリファクタリングとは？

リファクタリングとは、コードの外部から見た動作を変えずに、内部の構造を整理・改善する作業です。具体的には次のような改善が対象になります。

・命名の改善: 意味が不明な変数名・関数名を直感的に読めるものに変える
・重複の除去: 同じような処理が複数箇所にある場合、共通化して1箇所にまとめる
・関数の分割: 1つの関数が長くなりすぎている場合、役割ごとに分ける
・コメントの追加: 処理の意図が伝わらない箇所に説明を補う
・ネストの解消: if文やループが深くなりすぎている構造を平坦化する

従来はベテランエンジニアが時間をかけて手動で行う作業でしたが、AIを活用することで、コードを貼り付けてプロンプトを書くだけで改善案が得られるようになっています。

【Before/After例】AIリファクタリングで変わること

Before（リファクタリング前）:

def f(x, y, z):
    r = 0
    for i in range(len(x)):
        if x[i] > z:
            r += x[i] * y
    return r

After（AIリファクタリング後）:

def calculate_filtered_total(values: list, multiplier: float, threshold: float) -> float:
    """thresholdを超えるvaluesのみmultiplierを掛けた合計を返す"""
    return sum(v * multiplier for v in values if v > threshold)

変数名・関数名が意味のある英語になり、型ヒントとdocstringが追加されました。処理内容もリスト内包表記で簡潔になっています。

具体的な使い方（ステップバイステップ）

1. コードを貼り付けて現状分析させる

まず、AIに対象コードの問題点を把握させます。いきなり「直して」とお願いするより、現状分析を先に依頼する方が精度の高い提案が得られます。

以下のコードの問題点を分析してください。

【コード】
（ここにコードを貼り付ける）

【確認してほしいポイント】
・命名がわかりにくい変数・関数はどれか
・重複している処理はあるか
・関数が長すぎて分割すべき箇所はどこか
・ネストが深すぎて読みにくい箇所はあるか

問題点のリストとその理由を箇条書きで教えてください。

出力例:

問題点のリスト:
1. 命名の問題: 関数名 f()、変数 x/y/z/r/i が何を表すか不明
2. ドキュメント不足: 関数の目的・引数・戻り値の説明がない
3. 型情報なし: Pythonの型ヒントがなく、引数の型が不明
4. 最適化の余地: for + if の組み合わせはリスト内包表記で簡潔に書ける

2. リファクタリングを依頼するプロンプト

問題点を確認したら、具体的な改善を依頼します。一度に全部変えようとせず、優先度の高いものから順番に依頼するのがコツです。

先ほど分析したコードをリファクタリングしてください。

【改善してほしい点】
1. 関数名と変数名を意味のある英語に変える
2. Pythonの型ヒントを追加する
3. docstringで処理の目的・引数・戻り値を説明する
4. 可能であれば処理を簡潔にする

【制約】
・コードの外部から見た動作（入力と出力）は変えないこと
・既存のコードと同じPythonバージョン（3.9）で動作すること

改善後のコードと、変更した内容の説明をセットで提示してください。

重要: 「動作を変えないこと」という制約を必ず明示してください。これを省くと、AIが誤って仕様ごと変更してしまうケースがあります。

3. 命名（変数名・関数名）の改善を依頼する

既存システムに大量の不明瞭な命名がある場合、命名改善に特化した依頼が効果的です。

以下のコードの変数名・関数名を、意味が一目でわかる英語に改善してください。

【コード】
（ここにコードを貼り付ける）

【前提情報】
・このコードは「受注管理システム」の一部
・ユーザーは「注文」「顧客」「金額」「数量」を扱う
・チームの慣習としてスネークケース（snake_case）を使用

【出力形式】
変更前の名前 → 変更後の名前 という対応表を先に出してください。
その後、変更後のコードを提示してください。

前提情報（ドメイン知識）を伝えることで、業務の文脈にあった命名が提案されます。「注文管理」という背景があれば `d` → `order_data` のような具体的な変換が得られます。

4. 出力コードを確認して追加調整する

AIが提案したコードをそのまま使うのではなく、次のチェックを必ず行ってください。

・動作確認: テストを実行して、変更前と同じ結果が出るか確認する
・チームの規約確認: プロジェクトのコーディング規約（命名規則・コメントスタイル）に合っているか
・差分の確認: git diff で変更範囲が想定内かチェックする
・段階的な適用: 一度に全ファイルを変更せず、1つの関数や1ファイルから始める

AIはコードの文脈を完全には理解できないため、プロジェクト固有のルールや暗黙の前提は人間が確認する必要があります。

実務での活用例（Before/After）

【活用例1】レガシーPHPコードの命名改善

状況: 10年前に書かれたPHPコードに意味不明な変数名が大量にある。引き継いだ担当者が解読に苦労している。

Before（問題のあるコード）:

function proc($a, $b, $c) {
    $x = $a * $b;
    if ($x > $c) {
        $y = $x - $c;
        return $y * 1.1;
    }
    return $x;
}

After（AIによるリファクタリング後）:

/**
 * 割引後の支払い金額を計算する
 * @param float $unit_price 単価
 * @param int $quantity 数量
 * @param float $discount_threshold 割引適用の上限金額
 * @return float 最終支払い金額（割引超過分に10%追加）
 */
function calculate_final_price(float $unit_price, int $quantity, float $discount_threshold): float {
    $subtotal = $unit_price * $quantity;
    if ($subtotal > $discount_threshold) {
        $excess_amount = $subtotal - $discount_threshold;
        return $excess_amount * 1.1;
    }
    return $subtotal;
}

改善効果: 関数の役割が名前から一目でわかるようになり、コードレビューにかかる時間が大幅に短縮されました。

【活用例2】長すぎる関数の分割

状況: 1つの関数が200行以上あり、デバッグや修正に毎回時間がかかる。

以下の関数は200行を超えており、保守が困難です。
単一責任の原則に基づいて、役割ごとに小さな関数に分割してください。

【コード】
（200行の関数を貼り付け）

【条件】
・各関数は1つの役割のみ担う
・分割後の関数名は処理内容が伝わる英語にする
・元の関数は各小関数を呼び出す形でまとめる
・動作は変えない

分割の方針（どこで切るか）を先に説明してから、コードを提示してください。

「分割の方針を先に説明してから」というプロンプトがポイントです。AIの設計判断を先に確認できるため、人間の意図とズレがあれば修正指示を出せます。

うまくいかない時の対処法

【問題1】AIが動作を変えてしまった

リファクタリングのはずが、AIがロジックを変えてしまうことがあります。

対策: プロンプトに「動作を変えずに構造だけ改善してください。ロジックの変更は一切禁止」と明示します。また、変更前後でテストを実行して差異を確認する習慣をつけましょう。

【問題2】コードが長すぎてAIが全体を把握できない

1,000行を超えるファイルを一度に渡すと、AIが後半の内容を参照できなくなるケースがあります。

対策: ファイル全体でなく、関数単位・クラス単位で分割して渡します。「このファイルの get_order_total 関数だけをリファクタリングしてください」のように範囲を絞ってください。

【問題3】プロジェクト固有の命名規則が反映されない

AIが一般的なベストプラクティスに従った命名をするため、チームの規約と合わない場合があります。

対策: プロンプトに命名規則のサンプルを含めます。「このプロジェクトでは〇〇という命名パターンを使っています。例: getOrderById / createCustomer / updateInventory」のように、実際の例を3～5個示すだけで精度が上がります。

【問題4】AIの提案が正しいか判断できない

プログラミング経験が浅い場合、AIの提案が適切かどうか自分で判断しにくいことがあります。

対策: AIに「この変更のデメリット・リスクも教えてください」と追加で聞きます。良い面だけでなく問題点も挙げさせることで、見落としを防げます。また、小さな単位で変更してテストする習慣が安全です。

AIエラーログ解析の方法については、AIでエラーログ・スタックトレースを解析する方法も参考にしてください。

ツール別の特徴と使い分け

AIコードエディタの選び方については、AIコードエディタ比較｜Cursor・Windsurf・Claude Codeの違いと業務別の選び方で詳しく解説しています。

本記事のまとめ

AIを使ったコードリファクタリングの要点をまとめます。

・現状分析を先に依頼する: いきなり「直して」と言わず、まず問題点を挙げさせると精度が上がる
・「動作を変えない」を明示する: 制約を書かないとAIがロジックを変更してしまうことがある
・コンテキストを与える: ドメイン情報・命名規則の例・チームの規約をプロンプトに含める
・小さな単位で進める: 関数単位でリファクタリングし、テストで動作確認してから次に進む
・AIの提案を鵜呑みにしない: デメリット・リスクも確認して、人間がレビューする

レガシーコードの保守コストは、AI活用によって大幅に下げられます。まず小さなコードから試してみることをおすすめします。

AIを活用した開発環境の整備全般については、姉妹サイトDXマスターズ.TOKYOでDX推進の観点から詳しく解説しています。