22 Cursor Prompts for Refactoring & Clean Code (2026)

Refactor @[path/to/file] for readability without changing behavior.

Rules:
- Keep inputs, outputs, and side effects identical. Do not change the public API.
- Improve naming, structure, spacing, and early returns.
- Only edit this file — don't touch unrelated files.
- Show me a per-file diff before applying anything.
- After I accept, run the tests and confirm they still pass.
Flag anything that looks like a latent bug instead of silently fixing it.

Rename the unclear identifiers in @[path/to/file] for clarity.

Rules:
- Rename variables, functions, and params whose names don't say what they hold or do.
- Update every reference; if a symbol is used elsewhere, use @Codebase to find and update all call sites.
- Keep behavior identical — this is a pure rename, no logic changes.
- Don't rename anything that's part of the public/exported API unless I confirm.
- Show a per-file diff and run the tests after.

Simplify the conditional logic in @[path/to/file] (or the code I've selected).

Rules:
- Flatten nested if/else with guard clauses and early returns.
- Replace long boolean chains with well-named helper predicates.
- Keep the exact same truth table — every branch must behave as before.
- Don't touch unrelated code in the file.
- Show the diff, then run the tests to confirm behavior is unchanged.

In @[path/to/file], replace comments that explain "what" with self-explanatory code.

Rules:
- Where a comment describes what a block does, extract it into a well-named function or variable and delete the now-redundant comment.
- Keep comments that explain "why" (intent, gotchas, links to tickets).
- No behavior change — same inputs and outputs.
- Only this file; show a per-file diff and run the tests after.

Split the large function [functionName] in @[path/to/file] into smaller, single-responsibility pieces.

Rules:
- Extract logical units into well-named helpers; each does one thing.
- Keep behavior identical and note any hidden coupling or shared state you find.
- Don't change the function's public signature unless I say so.
- Keep the helpers in this file unless I ask to move them.
- Show a per-file diff, then run the tests and fix anything you broke.
Give me a one-line summary of each new helper's job.

Extract [the repeated JSX / this logic] from @[path/to/file] into its own [component / module] at [path/to/new-file].

Use Agent mode. Rules:
- Create the new file, move the code, and update @[path/to/file] to import and use it.
- Pass everything it needs via props/params — no new global state.
- Keep the rendered output / behavior identical.
- Outline your plan before editing, then show a per-file diff for every file you touch.
- Don't touch files other than these two.
- Run the tests after and fix any failures.

@[path/to/file] mixes [UI and data fetching / business logic and I/O / parsing and formatting]. Separate the concerns.

Rules:
- Split it so each unit has one responsibility (e.g. pull data access into a [service/hook], leave presentation behind).
- Keep the external behavior and public API identical.
- Show me the proposed structure first, then a per-file diff.
- Only touch the files needed for this split — list them before you start.
- Run the tests after and confirm they pass.

@[path/to/big-file] is too large. Break it into focused files without changing behavior.

Use Agent mode. Rules:
- Group related code and move each group into a clearly named sibling file.
- Update all imports across the repo (@Codebase) so nothing breaks.
- Keep every export's name and signature the same so callers don't change.
- Propose the split (which code goes where) before editing.
- Show a per-file diff for each file, run the tests, and fix failures.

Find and remove duplication in @[path/to/folder]. Use @Codebase to catch copies elsewhere.

Rules:
- Identify blocks that are the same or nearly the same, and factor them into one shared function/util.
- Only merge things that are genuinely the same concept — don't over-abstract coincidental similarity.
- Keep behavior identical at every call site; update them all.
- List the duplicates you found before changing anything.
- Show a per-file diff, run the tests, and fix any breakage.

Extract [this repeated logic] into a shared [util function / React hook] at [path/to/shared-file].

Use Agent mode. Rules:
- Create the shared [util/hook], give it a clear name and signature, and replace each duplicated occurrence with a call to it.
- Use @Codebase to find every place this pattern appears.
- Keep behavior identical everywhere; update all call sites.
- Show a per-file diff for the new file and each caller.
- Run the tests after and fix anything that fails.
Don't touch files that don't use this pattern.

@[path/to/reference-file] follows the pattern I want everywhere. Apply the same pattern to @[folder or list of files].

Rules:
- Match the reference file's structure, naming, and error handling in each target file.
- Change only what's needed to conform to the pattern — keep each file's behavior identical.
- Work one file at a time and show me a per-file diff before moving on.
- Don't touch files outside the ones I named.
- Run the tests after each file (or at the end) and fix failures.

Add accurate types to @[path/to/file].

Target: [TypeScript / Python type hints / etc.].
Rules:
- Add precise types for params, returns, and key variables. Avoid "any"/loose types unless truly unavoidable.
- Don't change runtime behavior — types only.
- Where a type reveals a possible bug or inconsistency, flag it in a comment instead of hiding it.
- Only this file; show a per-file diff.
- After, run the type-checker and the tests and report anything that fails.

Replace the loose "any" / unknown-shaped types in @[path/to/file] with precise ones.

Rules:
- Infer the real shape from how each value is used and from @[related types/interfaces].
- Introduce or reuse proper interfaces/types; no "any" unless you justify it in a comment.
- Don't change runtime behavior or the public API.
- If tightening a type reveals a mismatch, flag it rather than casting it away.
- Show a per-file diff, then run the type-checker and tests.

Add input validation to [functionName / the endpoint] in @[path/to/file].

Rules:
- Validate all external inputs (args, request body, query params) at the boundary before use.
- Use [the existing validation lib / a schema / manual checks — match what the codebase already does].
- Reject invalid input with a clear, specific error; don't change the happy-path behavior.
- Don't touch unrelated code.
- Show a per-file diff and run the tests; add a couple of tests for the new invalid-input cases.

Make error handling in @[path/to/file] explicit and consistent.

Rules:
- Replace swallowed errors, bare catch blocks, and silent failures with clear handling.
- Surface errors with context (what failed, with which input); don't leak internals to users.
- Follow the codebase's existing error pattern (@[error util / result type / logger]).
- Keep the happy-path behavior identical.
- Show a per-file diff, run the tests, and note any behavior that changed for error cases so I can confirm it's intended.

Migrate @[path/to/file or folder] from [library/framework old version] to [new version].

Use Agent mode. Reference @Docs for [library] and the migration guide.
Rules:
- Update the code to the new API, preserving behavior.
- List every changed call and what replaced it in a table.
- Flag deprecations and breaking changes I must test manually.
- If you're unsure about a current API detail, say so instead of guessing — check @Docs or @Web.
- Show a per-file diff, run the build and tests, and fix failures.
- Don't touch files that don't use this library.

Convert @[path/to/file].js to TypeScript.

Use Agent mode. Rules:
- Rename to .ts/.tsx and add accurate types for params, returns, and state. Avoid "any".
- Update imports/exports and any references to the old file across the repo (@Codebase).
- Keep runtime behavior identical — this is a typing pass, not a rewrite.
- Where a type exposes a bug, flag it rather than papering over it with a cast.
- Show a per-file diff, run the type-checker and tests, and fix errors.

Replace [old package] with [new package] across the code that uses it.

Use Agent mode. Reference @Docs for [new package].
Rules:
- Use @Codebase to find every import and usage of [old package].
- Rewrite each usage with the new package's equivalent API, preserving behavior.
- List the API mappings (old call -> new call) in a table.
- Remove [old package] from the dependency manifest once nothing imports it.
- Show a per-file diff, run the tests, and flag any behavior that can't be matched 1:1.

Modernize the syntax in @[path/to/file] to current [language/framework] idioms.

Rules:
- Apply modern equivalents (e.g. [callbacks -> async/await, var -> const/let, .then chains -> await, class components -> hooks] — whatever applies).
- Keep behavior identical; don't change the public API.
- Don't reformat or restructure code that's already modern.
- Only this file; show a per-file diff.
- Run the linter and tests after and fix anything that breaks.

Reorganize @[path/to/folder] into a cleaner structure.

Use Agent mode. Rules:
- Propose the new folder/file layout and the rationale BEFORE moving anything — wait for my OK.
- Once I approve, move files and update every import path across the repo (@Codebase).
- Don't rename symbols or change any behavior — this is purely a file-move.
- Show a per-file diff and the list of moved files.
- Run the build and tests after; nothing should break.

Introduce a [service / data-access / API] layer between @[caller files] and @[the code they call directly].

Use Ask mode first to plan, then Agent to implement. Rules:
- Define a clean interface for the new layer and route calls through it instead of reaching past it.
- Move the relevant logic behind the boundary; keep external behavior identical.
- Show me the interface and plan before editing.
- Update all call sites; show a per-file diff.
- Run the tests after and fix failures. Don't touch code unrelated to this boundary.

I want to [describe the large refactor, e.g. move to a feature-folder structure / extract a package / decouple X from Y]. Plan it before writing any code.

Use Ask mode (or Agent's plan step). Do this:
- Read the relevant code with @Codebase and @Folders and map what's affected.
- Propose a step-by-step plan, ordered so each step is small, testable, and shippable on its own.
- Call out the riskiest steps and how to de-risk them (e.g. add characterization tests first).
- List which files each step touches and how we'll verify behavior is unchanged.
Don't edit anything yet — just give me the plan and wait for me to approve step 1.