Cursor Run Agent で最大限の成果を得るには、やりたいことを具体化した高品質プロンプトが不可欠です。

今回はCursorを使ったリファクタリング支援でコード品質を劇的に改善させるコツをご紹介いたします。

プロンプト早見表

#	目的	やりたいこと	プロンプト	期待効果
1	巨大関数の可読性向上	肥大化した render を UI 部品ごとに切り出し、レビューしやすいサイズにしたい	render 関数が120行ある。これをUIブロックごとに最大20行の private 関数へ抽出し、コンポーネントの戻り型を維持	差分が明確になりレビュー時間を短縮
2	型安全の確保	暗黙 any が潜むユーティリティ群を型注釈付きで明確化	暗黙anyをすべて明示型へ置換。src/utils 配下が対象。JSDoc コメントは削除	コンパイルエラーゼロで品質を保証
3	ドメインモデルの統一	同義の User / Member を一つに集約し冗長実装を排除	User と Member を統合し、フィールド名は User に合わせる。Member を参照するファイルは import を自動更新	重複コードと命名ブレを削減
4	不要コードの除去	死活コード・未使用 import を除去してビルド負荷を下げる	src/**/*.ts から未使用 import と到達不能コードを削除。ESLint no-unused-vars を満たす	バンドルサイズと警告数を低減
5	命名規約の統一	内部コードの snake/camel 混在を camelCase に統一	snake_case と camelCase が混在。内部コードを camelCase に統一。公開 API 名は変更しない	読解速度が向上しミスが減少
6	テスト網の拡充	カバレッジが薄い util を高網羅テストで保護	utils/date.ts に対する Jest ユニットテストを生成。境界値と例外ケースを含め95%以上カバレッジ	リグレッション検知力を強化
7	データアクセス最適化	N+1 が出るクエリを JOIN でまとめて呼び出し回数を削減	N+1 が発生している repository/post.ts の findAllPosts を JOIN で先読みし型を維持	DB 負荷を大幅に削減
8	例外処理の一極化	分散した try/catch を共通ミドルウェアへ集約しログ統一	各 controller の try/catch を middleware/errorHandler.ts へ移動し共通ログ出力とスタックトレース整形を追加	障害解析を迅速化
9	依存逆転（DI 化）	直接 DB 呼び出しをリポジトリ層へ移しテスト容易化	service 層が直接 Prisma を呼んでいる。抽象 IPostRepository を domain 層に作成し、実装は infra/prisma へ移動	モック差し替え可能となり保守性向上
10	マジック値の排除	散在する数値リテラルを定数へ集約し保守性向上	src/**/*.ts の 10,30,86400 を config.ts へ切り出し。説明的な定数名を付与	仕様変更時の修正箇所を一元化

Cursor Run Agentで効率的にリファクタリングを行うには、目的を明確化した上で具体的なプロンプトを提示することが欠かせません。以下では10項目それぞれについて、見出し構成を統一し、プロンプトがLLMにどう解釈されるかと曖昧指示との違いを丁寧に解説いたします。

1. 巨大関数の可読性向上

やりたいこと

120行に膨張した render() を、UIブロック単位で20行以下の private 関数へ分割し、呼び出し側の型シグネチャを変えずに保守しやすくする。

プロンプト

promptCopy coderender 関数が120行ある。UIブロックごとに最大20行の private 関数へ抽出し、コンポーネントの戻り型を維持

プロンプトの解説

• 行数と上限値を数値で指定すると、LLMはASTを解析し「ここまでが20行」という物理的区切りを基準に抽出します。
• 戻り型を維持と明記することで、関数シグネチャが変更される事故を防ぎ、呼び出し側コードの改修コストをゼロに抑えます。

曖昧なプロンプトとの比較

指示	結果	問題点
「renderをいい感じに分割」	30〜40行の関数が複数残存し、型も暗黙変換	分割基準が不明確、呼び出し側が壊れる
上記プロンプト	4つの20行未満の関数へ抽出、型互換保持	差分が把握しやすく安全

変換例

tsxCopy codefunction render(items: Item[]) {
  const header = renderHeader(items);
  const list   = renderList(items);
  return <>{header}{list}</>;
}

renderHeader と renderList がそれぞれ18行・17行で収まり、可読性が飛躍的に向上します。

2. 型安全の確保

やりたいこと

src​/​utils 配下に潜む暗黙 any を具体的な型注釈に置き換え、JSDoc重複を排除してコンパイルエラーを撲滅する。

プロンプト

promptCopy code暗黙anyをすべて明示型へ置換。src/utils 配下が対象。JSDoc コメントは削除

プロンプトの解説

• ディレクトリ指定で誤編集を防止。
• JSDoc削除を明示し、型情報の重複を排除。
• LLMは呼び出し箇所を静的解析し、Union型やGenericsを自動推論します。

曖昧なプロンプトとの比較

指示	生成結果	評価
「anyをなくす」	多くが unknown に置換	手動修正が必要
上記プロンプト	具体型へ置換、tsc --noEmit が即時パス	理想的

変換例

tsCopy code// before
export function sum(a, b) { return a + b }
// after
export function sum(a: number, b: number): number { return a + b }

3. ドメインモデルの統一

やりたいこと

意味が重複する User と Member を統合し、命名ゆれと重複実装を排除する。

プロンプト

promptCopy codeUser と Member を統合し、フィールド名は User に合わせる。Member を参照するファイルは import を自動更新

プロンプトの解説

• 基準モデルを明示して型衝突を防止。
• 参照箇所のimport更新を指示し、循環参照を未然に回避します。

曖昧なプロンプトとの比較

指示	生成結果	問題点
「UserとMemberまとめて」	フィールドが両方残り重複	意味が統一されない
上記プロンプト	User基準で統合、不要型削除	一貫性◎

変換例

統合後、Member 型は削除され、全50ファイルのimportが自動で User に置き換わります。

4. 不要コードの除去

やりたいこと

未使用importと到達不能コードを削除し、ビルド時間とバンドルサイズを縮小する。

プロンプト

promptCopy codesrc/**/*.ts から未使用 import と到達不能コードを削除。ESLint no-unused-vars を満たす

プロンプトの解説

ESLintルール名を与えることで、LLMはASTをルールと照合し削除基準を誤判定しません。

曖昧なプロンプトとの比較

指示	警告数	評価
「不要コード消して」	12 警告残存	手動修正要
上記プロンプト	0	理想的

変換例

yarn eslint が警告ゼロで終了し、ビルド所要時間が15%短縮されます。

5. 命名規約の統一

やりたいこと

内部コードの snake_case を camelCase へ統一し、検索性と可読性を向上させる。

プロンプト

promptCopy codesnake_case と camelCase が混在。内部コードを camelCase に統一。公開 API 名は変更しない

プロンプトの解説

公開APIは残す条件を加え、破壊的変更を防ぎます。

曖昧なプロンプトとの比較

指示	外部API	内部統一	評価
「camelCaseに直して」	API名まで変更	〇	互換性×
上記プロンプト	変更なし	〇	互換性◎

変換例

user_name → userName へ置換され、exportシグネチャは保持されます。

6. テスト網の拡充

やりたいこと

カバレッジが薄い utils​/​date.ts を95%以上でテスト保護し、将来のリグレッションを防ぐ。

プロンプト

promptCopy codeutils/date.ts に対する Jest ユニットテストを生成。境界値と例外ケースを含め95%以上カバレッジ

プロンプトの解説

数値目標によりLLMは正常系だけでなく境界値・異常系を自動生成します。

曖昧なプロンプトとの比較

指示	カバレッジ	評価
「テスト作って」	68%	不十分
上記プロンプト	96%	十分

変換例

テーブル駆動テストが生成され、yarn jest --coverage が閾値を満たします。

7. データアクセス最適化

やりたいこと

findAllPosts のN+1クエリをJOINにまとめ、DB呼び出し回数を削減する。

プロンプト

promptCopy codeN+1 が発生している repository/post.ts の findAllPosts を JOIN で先読みし型を維持

プロンプトの解説

問題点・解決策・型維持を同時指示し、副作用を抑制します。

曖昧なプロンプトとの比較

指示	呼び出し回数	型互換
「N+1直して」	15	崩れる
上記プロンプト	3	保持

変換例

LEFT JOIN を導入し、平均応答時間が300 ms短縮。

8. 例外処理の一極化

やりたいこと

各Controllerに散在する try​/​catch を共通ミドルウェアへ移動し、ログ形式を統一する。

プロンプト

promptCopy code各 controller の try/catch を middleware/errorHandler.ts へ移動し共通ログ出力とスタックトレース整形を追加

プロンプトの解説

移動先ファイルと追加機能を明示することで、LLMはimportを自動調整し、ログ構造体を共通化します。

比較

曖昧指示だとlog整形が統一されず、循環参照が発生するリスクがあります。

変換例

全14Controllerからエラーハンドラが削除され、errorHandler.ts で一元管理されます。

9. 依存逆転（DI 化）

やりたいこと

Service層が直接Prismaを呼ぶ構造をリポジトリ層経由へ変更し、テスト容易性を高める。

プロンプト

promptCopy codeservice 層が直接 Prisma を呼んでいる。抽象 IPostRepository を domain 層に作成し、実装は infra/prisma へ移動

プロンプトの解説

抽象名と層配置を明示し、依存方向を固定します。

比較

曖昧指示ではインターフェース名が不統一になり、DIコンテナ設定が壊れがちです。

変換例

PostService が IPostRepository へ依存し、テスト時にモック実装を注入可能となります。

10. マジック値の排除

やりたいこと

散在する 10、30、86400 を定数へ切り出し、一元管理で保守性を向上させる。

プロンプト

promptCopy codesrc/**/*.ts の 10,30,86400 を config.ts へ切り出し。説明的な定数名を付与

プロンプトの解説

対象値を列挙し、LLMに誤置換をさせません。定数名要求でコード意図を自動ドキュメント化します。

比較

「マジック値を定数に」だけでは数値全体が検索・置換され、副作用を生む危険があります。

変換例

tsCopy code// config.ts
export const RETRY_LIMIT   = 10;
export const PAGE_SIZE     = 30;
export const SECONDS_IN_DAY = 86400;

変更後、全ファイルで直値が定数参照に置き換わります。

まとめ

#	ポイント	効果
1	対象範囲をパスまたは行数で限定	誤編集・過剰編集を防止
2	制約（型維持・API互換）を宣言	破壊的変更を回避
3	数値目標 (行数上限・カバレッジ) を設定	LLM に具体基準を与え品質を保証
4	Plan → Apply → 自動テストのループを徹底	差分確認と品質担保を両立

これらを守れば 巨大関数分割・型安全化・モデル統合・N+1 解消など の複雑なリファクタリングでも、想定外の副作用が少なく対応できます。

ぜひ「高粒度プロンプト設計 + Cursor Run Agent」のを活用し、コード品質を高めていっていただければと思います。

関連リンク

• Cursor Features
• Cursor Changelog
• Run Agent 公式ガイド