Automating Refactoring of Legacy JavaScript Code with Claude Code and Cursor
Machine-translated from Italian. Read the original
Introduction
Inherited JavaScript code from old projects is often plagued by technical debt (nested callbacks, excessive use of var, overly long functions, unnecessary dependencies). Automating refactoring with AI assistants integrated into IDEs can reduce risks, speed up iterations, and maintain test coverage.
Available AI Tools
- Claude Code (Anthropic) – IDE plugin that performs automatic code review and suggests changes based on best‑practice patterns. According to an article on HTML.it, Claude Code can analyze an entire file and propose contextual refactorings directly in the editor.
- Cursor – IDE with a built‑in AI assistant (based on OpenAI models). It offers completions, explanations, and on‑demand code transformations.
Identifying Technical Debt Patterns
- Callback hell / Nested Promises – look for functions passed as arguments to
thenorcatchwithout usingasync/await. - Global variables or
var– locate declarations withvaror assignments to undeclared properties. - Overly long functions – typical threshold > 50 lines; AI can suggest extracting helpers.
- Unused imports / obsolete dependencies – static analysis to find unreferenced
require/importstatements.
How to Make Claude Code or Cursor Recognize These Patterns
// Prompt for Claude Code (in editor)
"Analyze this file and point out every place where nested callbacks or var are used. Propose a version with async/await and let/const."
# Prompt for Cursor
"Refactor this function to use async/await and replace var with const where possible. Keep the existing tests passing."
Generating Safe Refactorings
| Step | Action | Note |
|---|---|---|
| 1 | Run the scan with the extension (e.g., Claude Code → Run Review). | The output is a list of suggestions with line references. |
| 2 | Apply suggestions one‑by‑one using the Apply suggestion feature or copy/paste into a dedicated branch. | Keep an atomic commit for each refactoring. |
| 3 | Refactor incrementally: start with low‑risk changes (e.g., var → let), then move to more complex ones (callback → async/await). | |
| 4 | Run linting (ESLint configured with eslint:recommended and plugin:prettier/recommended). | Verify that no new warnings are introduced. |
Validation with Automated Tests
- Run the test suite before refactoring (
npm test). - Generate coverage (
nyc npm testorjest --coverage). Save the report. - After each refactoring, re‑run the tests and compare coverage. A drop > 1 % should halt the process.
- Regression tests: if no tests exist, quickly add unit tests for the most critical functions before refactoring.
Recommended Workflow (step‑by‑step)
- Create a branch
refactor/ai-js-legacy. - Run lint and tests to establish a baseline.
- Launch Claude Code on all
.js(or.ts) files. - Filter suggestions: accept those marked low‑risk (e.g., formatting,
var→let). - Commit with a clear message (
refactor: replace var with let). - Move to more complex refactorings (callback → async/await) using Cursor to generate the new code.
- Re‑run tests and coverage; if everything passes, merge with a human‑reviewed PR.
- Document the removed patterns in a
DEBT.mdfile for future reference.
Best Practices and Caveats
- Don’t rely 100 % on AI: assistants can introduce logical regressions; human review remains mandatory.
- Branch backup: before applying massive suggestions, create a tag (
pre-ai-refactor). - Node version: ensure the project supports the generated syntax (e.g.,
async/awaitrequires Node ≥ 7.6). - Dependency management: update
package.jsononly after confirming that tests pass with the new versions.
Questions for the Community
- What criteria do you use to decide if an AI suggestion is low‑risk and can be accepted without review?
- Do you have concrete experiences integrating Claude Code or Cursor into CI pipelines? How do you automate validation of the refactorings?
- Which technical‑debt patterns do you find hardest to refactor automatically in legacy JavaScript projects?