【実務・中級編】Cursorで学ぶリファクタリング術：レガシーコードをモダンに書き換えるAI活用法 – 軽量・高機能テキストエディタ生産性向上バイブル

レガシーコードの墓場から抜け出せ：Cursorがもたらすパラダイムシフトと実戦的リファクタリング術

開発現場のテックリードとして、私たちは日々「技術的負債」という名のモンスターと戦っている。5年前に書かれたスパゲッティコード、型安全を無視したJavaScriptの山、誰も全体像を把握していない巨大なモノリス。これらを人間が手動でリファクタリングするのは、地雷原を裸足で歩くようなものだ。

しかし、VS Codeのフォークであり、コードベース全体のコンテキストを理解するAIエディタ「Cursor」の登場によって、このゲームのルールは完全に変わった。

単に「コードを綺麗にして」とチャットに投げ込むだけでは、おもちゃのコードしか返ってこない。プロフェッショナルが求めるのは、既存の振る舞い（仕様）を完全維持したまま、AST（抽象構文木）レベルでモダンな設計・構文へと昇華させる自動化パイプラインだ。

本稿では、Cursorの深部までを熟知したアーキテクトの視点から、レガシーコードを近代的なモダンスタックへ高速かつ安全に移行させるための実践知を余すところなく伝授する。

—

1. 開発スピードを劇的に高める：Cursor隠しコマンド＆キーバインド

マウスに手を伸ばした瞬間から、エンジニアの認知負荷は高まり、フロー状態は途切れる。Cursorの真価を発揮させるには、以下のキーボードショートカットを脳に焼き付け、反射で操作できるようにする必要がある。

特に `Cmd + I`（Composer）は、レガシーなMVC構造からレイヤードアーキテクチャへの移行など、ファイル群の移動と書き換えを同時に行う際に神がかった威力を発揮する。

—

2. チーム開発の生産性を底上げする：`.cursorrules` の極意

個人がどれだけCursorを使いこなしても、チームメンバー全員の出力品質がバラバラであれば、コードレビューのボトルネックは解消されない。ここで重要になるのが、プロジェクトルートに配置する `.cursorrules` ファイルだ。

このファイルは、AIに対する「プロジェクト固有の憲法」であり、コード生成時に必ず守るべきルールやアーキテクチャ制約を強制するためのものである。

実用的な `.cursorrules` のベストプラクティス構成

以下の設定をプロジェクトのルートに配置することで、AIはチームのコーディング規約を完全に理解した状態でコードを生成するようになる。

.cursorrules – Project Architecture & Coding Standards

1. Tech Stack & Core Philosophy

Language: TypeScript 5.x (Strict mode enabled, no `any` allowed).
Framework: Next.js 14+ (App Router), React Server Components (RSC) by default.
Styling: Tailwind CSS. Avoid inline styles or CSS modules unless strictly necessary.
State Management: Zustand for global client state, Server Actions for mutations.

2. Refactoring Rules (Legacy to Modern)

Convert all legacy `class` components or old `React.FC` functional components into modern functional components with explicit TypeScript interfaces.
Replace all legacy `Promise` chains (`.then().catch()`) with `async/await` and robust `try/catch` error boundaries.
Ensure all business logic is decoupled from UI components into custom hooks or server-side service layers.

3. Code Quality & Testing

Every new or refactored function/component MUST include unit tests using Vitest and React Testing Library.
Do not use `console.log` for debugging; use the centralized `@utils/logger`.
Import paths must use absolute paths with `@/` alias, relative paths with `../../` are strictly forbidden.

このファイルを置くだけで、AIが勝手に相対パスを使ったり、型安全を無視したコードを書く確率がほぼゼロになる。チーム全体のコード品質がボトムアップされる瞬間だ。

—

3. 絶対に入れるべき神プラグインと競合排除の鉄則

CursorはVS Codeの拡張機能をそのまま利用できるが、AIアシスト機能と競合するものや、パフォーマンスを悪化させるレガシーなプラグインを入れては本末転倒だ。

必須インストールすべき拡張機能

1. Error Lens (`usernamehw.errorlens`)

理由: エディタ上で行単位でエラーや警告をインライン表示する。AIが生成したコードの型ミスマッチや構文エラーを視覚的に即座に検知し、修正ループを高速化する。

2. GitLens (`eamodio.gitlens`)

理由: 「なぜこのレガシーコードがこの実装になっているのか（誰が、いつ、何のチケットで書いたか）」をコンテキストとして把握するため。AIにコードを読み込ませる際、Gitの歴史的背景も非常に重要なヒントになる。

3. Vitest (`vitest.explorer`)

理由: リファクタリング後のテスト駆動開発（TDD）において、テストの実行と結果をエディタ内でシームレスに確認するため。

導入してはいけない（競合・劣化する）拡張機能

GitHub Copilot / Codeium などの競合AIプラグイン: CursorのネイティブAIエンジンと競合し、補完のレイテンシ悪化や予期せぬ挙動を引き起こすため、必ず無効化またはアンインストールすること。

—

4. レガシーコードを最新スタックへ変貌させる：実践リファクタリング・ワークフロー

ここからが本題だ。実際のレガシーコードを想定し、Cursorを用いて安全かつモダンに書き換える手順を解説する。

ターゲット：Callbacks地獄のレガシーAPIクライアント

以下の、エラーハンドリングが曖昧で、古いコールバック構文を使ったJavaScriptのレガシーコードを、TypeScriptのモダンなカスタムフックへと生まれ変わらせる。

【Before】レガシーコード (`legacy-api.js`)

// 古いコールバック地獄とエラーハンドリングの欠如
function fetchUserData(userId, callback) {
setTimeout(function() {
if (!userId) {
callback(new Error(“User ID is required”), null);
} else {
// 擬似的なレガシーAPIレスポンス
var data = { id: userId, name: “John Doe”, legacyRole: “admin” };
callback(null, data);
}
}, 1000);
}

ステップ1: Composer (`Cmd + I`) による構造的リファクタリング

エディタ上で `Cmd + I` を押し、Composerを開いて以下のプロンプト（指示文）を入力する。

> プロンプト:
> `legacy-api.js` を読み込み、TypeScriptのモダンスタイル（`async/await`、厳格な型定義、カスタムフックまたはサービスクラス）に全面書き換えしてください。ファイル名も `userService.ts` に変更し、既存の振る舞いを完全に維持してください。

ステップ2: AIによる自動生成コードの精査

CursorのComposerは、数秒で以下のようなモダンなTypeScriptコードを生成する。

【After】モダン化されたコード (`userService.ts`)

ユーザー情報の型定義

/
export interface User {
id: string;
name: string;
role: ‘admin’ | ‘user’;
}

カスタムエラークラスの定義

/
export class UserFetchError extends Error {
constructor(message: string) {
super(message);
this.name = ‘UserFetchError’;
}
}

非同期処理によるモダンなユーザーデータ取得サービス
@param userId 取得対象のユーザーID
@returns ユーザーエンティティのPromise
@throws {UserFetchError} ユーザーIDが無効な場合

/
export async function fetchUserData(userId: string): Promise {
// 非同期処理のモック（実務ではfetchやaxiosに置き換え）
return new Promise((resolve, reject) => {
setTimeout(() => {
if (!userId) {
reject(new UserFetchError(‘User ID is required’));
} else {
resolve({
id: userId,
name: ‘John Doe’,
role: ‘admin’, // legacyRoleから正規化されたフィールド名
});
}
}, 1000);
});
}

人間が行うべき作業は、生成されたコードの型定義がプロジェクトの規約に合致しているかをレビューし、「Accept」ボタンを押すことだけだ。

—

5. テストコードの自動生成とAIによる品質チェック

コードをモダンに書き換えただけでは、リファクタリングは完了していない。「動くことを証明するテストコード」があって初めてリファクタリングは成立する。

テスト生成の手順

1. 新しく作成した `userService.ts` をエディタで開く。
2. `Cmd + L` を押してチャットペインにコンテキストを読み込ませる。
3. 以下のプロンプトを送信する。

> プロンプト:
> この `userService.ts` に対する包括的な単語テストを Vitest と `@testing-library/react`（または標準のVitest環境）を用いて作成してください。正常系（データ取得成功）と異常系（ID未指定時のエラー送出）の両方をカバーし、モックを含めたベストプラクティスなテストコードを記述してください。

生成されるテストコード (`userService.test.ts`)

import { describe, it, expect } from ‘vitest’;
import { fetchUserData, UserFetchError } from ‘./userService’;

describe(‘userService refactored tests’, () => {
// 正常系のテスト
it(‘should fetch user data successfully when valid userId is provided’, async () => {
const userId = ‘123’;
const user = await fetchUserData(userId);

expect(user).toEqual({
id: ‘123’,
name: ‘John Doe’,
role: ‘admin’,
});
});

// 異常系のテスト
it(‘should throw UserFetchError when userId is missing’, async () => {
// @ts-expect-error – Testing invalid runtime input intentionally
await expect(fetchUserData(”)).rejects.toThrow(UserFetchError);
});
});

このテストを `Vitest` エクスプローラーやCLIで実行し、グリーンになることを確認する。ここまでがCursorを活用した高速かつ安全なリファクタリングの全貌だ。

—

総括：AIエディタ時代におけるエンジニアの役割

レガシーコードの近代化において、Cursorは単なる「コード補完ツール」ではない。それは、人間の代わりに退屈でミスの起きやすい構文変換をミリ秒単位でこなし、私たちは「アーキテクチャの設計」と「ビジネス価値の創出」に集中させるための最強の相棒である。

`.cursorrules` による環境の標準化、Composerを駆使したアトミックなファイル書き換え、そして確実なテスト生成。これらをチームのワークフローに組み込むことで、技術的負債に怯える日々に終止符を打つことができる。

今すぐあなたのプロジェクトに `.cursorrules` を置き、レガシーの海へ飛び出そう。開発のスピードとコードの美しさが劇的に変わる瞬間を、ぜひ体感してほしい。