Legacy JavaScript rarely comes with a complete specification. Its real contract lives in callers, tests, production workarounds, and behaviors nobody remembers choosing. A useful coding assistant prompt makes that contract explicit before asking for cleaner code. Follow this numbered workflow to turn an unfamiliar module into a sequence of reviewable, behavior-preserving changes.
1. Define the JavaScript refactoring boundary
Choose one function or module, not an entire directory. State the problem you want to solve and identify what must remain unchanged. Include the supported runtime, module system, public exports, and dependency restrictions when known. Ask the assistant to flag missing information rather than invent it.
Prompt: Inspect this module and its direct callers. Our goal is to separate input normalization from request construction. Preserve public exports, synchronous return values, thrown errors, and side-effect order. Do not edit files yet. List uncertainties and propose the smallest useful refactoring boundary.
2. Map observable behavior before requesting edits
Ask for evidence tied to file paths and function names. Legacy behavior may depend on object mutation, callback timing, property enumeration, or coercion. A broad instruction such as “modernize this code” gives the assistant permission to change more than you intended.
Prompt: Trace the selected function through its direct callers. Identify inputs, outputs, mutations, external calls, and error paths. Distinguish behavior supported by tests from behavior inferred from implementation. Highlight assumptions about null, undefined, empty strings, zero, and false. Report findings without changing code.
3. Capture existing behavior with characterization tests
Before restructuring, record what the implementation actually does. Characterization tests are not an endorsement of every quirk; they make accidental changes visible. Use the existing test runner and conventions. If a suspicious behavior looks like a bug, record it separately instead of silently correcting it.
Prompt: Add characterization tests for the selected function using the current test framework. Cover representative success cases, boundary inputs, error behavior, observable mutations, and dependency interactions. Preserve existing behavior, including surprising results. Do not change production code. Explain what each test protects.
4. Request one mechanical JavaScript change
Once the baseline is captured, choose a single transformation: extract a helper, rename a local variable, or replace duplicated expressions. Keep semantic migrations separate. Converting callbacks to promises, changing CommonJS to ES modules, or replacing loose equality can alter behavior and deserves its own decision.
Prompt: Extract input normalization into a private helper. Keep conditions, coercion, evaluation order, and mutation behavior unchanged. Do not modify exports, dependencies, asynchronous control flow, or unrelated formatting. Make only the requested transformation and explain any unavoidable changes outside that boundary.
5. Review the patch for hidden semantic changes
Read the diff yourself, then ask the assistant to challenge it. Watch for lost method receivers, changed exception handling, newly shared objects, and altered short-circuit behavior. Replacing a fallback based on truthiness with a null-only fallback, for example, changes how zero and empty strings are handled.
Prompt: Review this diff specifically for behavior changes. Check receiver binding, closure capture, mutation, evaluation order, coercion, exception propagation, and callback timing. Cite each concern against the original implementation. Do not expand the refactor or fix unrelated issues.
6. Validate the JavaScript patch with recorded evidence
Request the relevant tests and existing lint checks, but distinguish execution from suggestions. An assistant without terminal access cannot honestly report a passing suite. If checks fail, determine whether the patch introduced the failure before broadening the scope.
Prompt: Run the targeted characterization tests and relevant existing checks if execution is available. Report exact commands, outcomes, and failures. Separate checks actually run from checks merely recommended. If a failure appears unrelated, explain the evidence. Do not claim validation you could not perform.
7. Repeat with portable prompts and a clean checkpoint
Commit or otherwise checkpoint the reviewed patch before selecting another transformation. Carry forward the behavior contract, relevant tests, and unresolved questions rather than an entire conversation. This makes subsequent prompts easier to audit and reduces dependence on unstated context.
For teams using different coding assistants, SwiftRelay offers pay-as-you-go, per-token access across model providers and works with Claude Code, Codex, Gemini CLI, and OpenAI-compatible SDKs. Sign up for SwiftRelay to try this workflow with the small gift credit available to new accounts.
Next-patch prompt: Using the recorded contract and passing baseline, propose the next smallest refactoring step. Explain its benefit, behavioral risks, and required tests. Wait for approval before editing.