Legacy JavaScript is code people depend on but hesitate to change. It may have unclear names, nested callbacks, or surprising rules that nobody documented. A coding assistant can help untangle it, but “clean this up” leaves too much room for guesses. Your first lap should produce a small, reviewable change—not a rewritten application.
Define what your JavaScript refactor must preserve
Refactoring means changing the structure of code without intentionally changing its observable behavior. That includes returned values, thrown errors, mutations, and side effects such as network requests. A shorter function is not an improvement if it quietly changes what callers receive.
Start with one function or module. Give the assistant its relevant callers, available tests, and runtime constraints. Mention whether the project uses browser scripts, CommonJS, or JavaScript modules. Do not paste credentials, customer records, or production secrets.
Starter prompt: “Help me refactor this JavaScript function without changing its observable behavior. First explain its inputs, outputs, side effects, and assumptions. Identify missing context and ask questions before editing. Keep the existing module format and supported runtime.”
Ask the assistant to map behavior before editing
Old code often contains accidental rules that have become part of the product. For example, a default applied with a logical OR operator treats zero and an empty string as missing values. Replacing it with nullish coalescing changes that behavior, even if the replacement looks more modern.
Inspection prompt: “Do not modify the code yet. List its decision branches and observable behavior. Pay particular attention to missing properties, null, undefined, zero, empty strings, mutation, and error handling. Separate facts visible in the code from assumptions about its callers.”
Check that explanation against the actual code. The assistant’s confidence is not evidence. If a helper function is missing, provide it or keep the proposed change away from that boundary.
Capture current JavaScript behavior with tests
Characterization tests record what the code does today. They provide a reference point while you reorganize it. They do not prove that the existing behavior is correct, and they should not quietly turn a suspected bug into a permanent requirement.
Testing prompt: “Using our existing test framework, propose characterization tests for this function. Cover a normal case, relevant boundary values, and failure behavior. Label surprising behavior for human review. Do not change the implementation or introduce a new test dependency.”
Run those tests against the original implementation first. If you cannot run them, ask for the exact command and report that verification is still pending. Never treat generated tests as passing tests until they have actually run.
Request one bounded JavaScript change
Once you understand the behavior, choose a narrow improvement. Renaming local variables or extracting one repeated calculation is easier to review than combining dependency upgrades, asynchronous rewrites, and formatting changes.
Refactoring prompt: “Refactor only this function to reduce nesting. Preserve return values, error behavior, mutation, and the order of side effects. Keep the public interface unchanged. Add no dependencies and avoid unrelated formatting. Explain any change you cannot confidently make behavior-preserving.”
- Set a boundary: Name the file and function the assistant may edit.
- Set a stopping rule: Ask it to pause if the change requires modifying callers.
- Request a review guide: Ask which changed lines carry the greatest behavioral risk.
Review the diff before accepting the refactor
Read the patch, not just the explanation. Watch for changed equality checks, lost method context, altered object mutation, and reordered asynchronous work. Run the relevant tests, lint checks, and build commands available in your project.
Review prompt: “Compare the original and refactored versions for behavior differences. Focus on coercion, exceptions, mutation, and execution order. List checks actually run separately from checks merely recommended. Do not claim equivalence beyond the evidence.”
Keep your refactoring prompts portable with SwiftRelay
Save these prompts alongside your project’s runtime and testing notes. If you use Claude Code, Codex, or Gemini CLI, SwiftRelay provides pay-as-you-go access to multiple models through a shared relay. Sign up for SwiftRelay to try this workflow with the small gift credit for new accounts. Keep each task bounded: inspect, test, change, and verify before starting the next lap.