22 Windsurf Prompts for Refactoring & Clean Code (2026)

In Write mode, refactor @file:[path/to/file] for readability ONLY.

Hard rules:
- No behavior change. Keep the public API and return values identical.
- Do not touch any other file.
- Run [test command, e.g. npm test] BEFORE you start and confirm it passes; run it again AFTER and confirm it still passes.

Improve naming, break up long expressions, and add short comments only where intent is unclear. Show me the per-file diff and the final test output.

@file:[path/to/untested-file] has no tests. Before we refactor it, write characterization tests that pin its CURRENT observable behavior — including edge cases and error paths — in [test framework].

Do not change the source file yet. Run the new tests and confirm they pass against the existing code. Report anything you couldn't cover.

In Chat mode (read-only), read @file:[path] and propose a step-by-step refactoring plan to improve [readability / testability / structure].

For each step, state: what changes, why, and the risk of a behavior change. Do NOT edit anything yet. I'll approve the plan, then you execute it one step at a time and run [test command] after each step.

Refactor @file:[path] end to end. Goals, in priority order:
1. No behavior change (verify with [test command]).
2. Consistent naming and formatting with the rest of @folder:[dir].
3. Smaller functions, fewer nesting levels, no dead code.

Constraints: only edit this one file; keep all exports and their signatures. Acceptance: tests pass and the public interface is byte-for-byte the same. Show the diff.

The function [functionName] in @file:[path] is too long and does several things. Extract each distinct responsibility into its own well-named helper function in the same file.

Rules: no behavior change; keep [functionName]'s signature and return value identical; the extracted helpers should be pure where possible. Run [test command] after and confirm green. Show me the diff grouped by helper.

@file:[path/to/big-module] has grown too large. Split it into cohesive files under @folder:[target-dir], grouping by responsibility.

Requirements:
- Preserve the public API: re-export everything from an index/barrel so existing imports keep working.
- Use @codebase to update any internal imports that break.
- No behavior change. Run [test command] and confirm all tests pass.
Do not modify files outside [target-dir] except imports that must change. Show the new file list and the diff.

@file:[path/to/handler] mixes HTTP/route logic with business logic and data access. Introduce a clear boundary: keep the handler thin and move business logic into a [service/use-case] module, and data access behind a [repository] interface.

Rules: no behavior change; the route's request/response contract stays identical; add no new dependencies without asking. Run [test command] after. Explain the new layering in 3 bullets and show the diff.

Look at @function:[name] in @file:[path]. It has a growing if/else (or switch) on [some type/flag]. If — and only if — a [Strategy / Factory / State] pattern genuinely simplifies it, refactor to that pattern; otherwise tell me why it isn't worth it and stop.

If you proceed: no behavior change, keep the same inputs/outputs, and run [test command]. Show the diff and a one-line rationale.

Use @codebase to find blocks duplicated between @file:[fileA] and @file:[fileB] (and anywhere else). Extract the shared logic into a single well-named helper in [shared/util path] and update all call sites to use it.

Rules: no behavior change; if the "duplicates" differ in a meaningful way, keep them separate and tell me. Run [test command] and confirm green. Show me each replaced call site in the diff.

I think [functionName / export / file] is unused. Use @codebase to search the entire repo for any references, imports, dynamic usage, or string-based lookups of it.

If there are zero real references, delete it and any now-orphaned imports. If there is ANY reference, do not delete — list where it's used. Run [test command] after. Show the diff and the list of references you found.

Refactor @function:[name] in @file:[path] to reduce nesting. Use guard clauses / early returns to handle edge and error cases up front, so the happy path is flat and unindented.

No behavior change — every branch that returned or threw before must still return or throw the same thing. Run [test command] after and confirm green. Show the diff.

In @file:[path], find magic numbers and hard-coded string literals that carry meaning (timeouts, limits, status codes, keys) and replace them with named constants at the top of the file or in [constants module].

Rules: values must be identical — no behavior change; don't touch literals that are self-explanatory (like 0, 1, or array indices). Run [test command] after. Show the diff.

Convert @file:[path.js] to TypeScript (or add JSDoc types if we're staying JS). Infer accurate types from usage across @codebase — don't fall back to `any`.

Rules: runtime behavior must not change; keep exports and their names identical; update imports of this file as needed. Run [type-check command, e.g. tsc --noEmit] and [test command] and confirm both pass. Flag anything you genuinely couldn't type and why.

Add precise type hints to every function and method in @file:[path.py], inferring types from how callers use them (@codebase) and from return values.

Rules: no runtime behavior change; use standard `typing` constructs; add `from __future__ import annotations` if it helps. Run [mypy / pyright] and [test command] and confirm both are clean. List any signatures you had to leave as loose types.

Use @codebase to find `any`, `unknown` used as a cop-out, and overly broad types in @folder:[dir]. Replace them with precise types or discriminated unions based on real usage.

Rules: no behavior change; do not add runtime casts to silence the checker — fix the type instead. Run [type-check command] and [test command]. Show me each tightened type in the diff with a one-line note on what it now guarantees.

Modernize @file:[path] to current [language/framework] idioms: [e.g. var → const/let, promises → async/await, .then chains, deprecated API X → Y]. Use @docs:[library] to confirm the current recommended API.

Rules: no behavior change; don't upgrade dependency versions; keep the public interface identical. Run [test command] after. Show the diff and list any deprecated API you replaced.

Refactor @function:[name] in @file:[path] to use async/await consistently. Remove nested callbacks and `.then()` chains, and make sure every awaited call has proper error handling (try/catch or a single rejection path).

Rules: no behavior change, including the order of side effects and the exact errors thrown; no unhandled promise rejections. Run [test command] after and confirm green. Show the diff.

Rename [oldName] to [newName] across the whole project. Use @codebase to find the definition and EVERY reference — call sites, imports/exports, type usages, and any string references (config keys, tests, docs).

Rules: no behavior change; update all references so nothing breaks; don't rename unrelated symbols that merely contain the substring. Run [test command] after. Show me a per-file diff so I can review each change before accepting.

We're upgrading [library] from [vX] to [vY]. Use @docs:[library] for the vY migration guide and @codebase to find every place we use it.

Plan first (Chat mode): list each breaking change that affects us and the file it touches. After I approve, apply the changes in Write mode, one concern at a time, running [test command] after each. Rules: no behavior change beyond what the upgrade requires; explain any unavoidable behavior change. Show diffs per file.

Convert the class component in @file:[path] to a function component using hooks. Map lifecycle methods to the right hooks (componentDidMount/Update/Unmount → useEffect), state to useState/useReducer, and keep refs and context wiring intact.

Rules: no behavior change — same rendered output, same props/state contract, same effect timing. Run [test command] after and confirm green. Show the diff and note any effect whose timing you had to reason about carefully.

Create a reusable workflow file at .windsurf/workflows/apply-codemod.md that performs this repeated refactor across a folder I specify:

1. Use @codebase to list every file in [folder] matching [pattern].
2. For each file, apply this transform: [describe the exact mechanical change].
3. After each file, run [test command]; if it fails, stop and report that file.
4. Never touch files outside the given folder.

Write the workflow so I can invoke it later with /apply-codemod. Show me the file contents.

Create a rule file at .windsurf/rules/[area]-conventions.md with a Glob trigger matching [glob, e.g. src/services/**/*.ts]. The rule should state our conventions:

- Naming: [e.g. camelCase functions, PascalCase types, files kebab-case].
- Error handling: [e.g. throw typed AppError, never bare strings; wrap external calls in try/catch and log with context].

Then apply these conventions across @folder:[dir] now: rename and adjust to match, with no behavior change. Run [test command] after. Show the rule file and the diff.