Integrating Claude Code into a VS Code workflow for automated refactoring

Claude Code is a beast for refactoring because it actually has a shell and a file system, unlike the chat windows we're used to in Copilot or Cursor. While I still use Cursor for the "surgical" edits and autocomplete, I've started offloading the heavy lifting—like migrating a whole module from CommonJS to ESM or renaming a core data structure across ten files—to Claude Code via the terminal.

The secret to making this work without it hallucinating your entire directory into oblivion is to treat it as a "headless" architect. I don't let it just "refactor the project"; I feed it a specific architectural goal and let it execute the file changes, which I then review via the VS Code Git lens.

My current workflow looks like this:

1. The "Context Seed" Prompt
Instead of vague requests, I use a prompt that forces it to map the dependencies first. If I'm refactoring a messy API service, I start with:

claude "Analyze the dependencies of /src/services/api.ts. List every file that imports these methods. Once mapped, propose a refactoring plan to move the auth logic into a separate middleware folder, but do not apply changes yet."

2. Controlled Execution
Once I've verified its plan in the terminal, I give it the green light. This is where the productivity gain kicks in. It doesn't just suggest code; it runs sed or writes the files directly. I keep my VS Code window open on the side; as Claude Code edits files, they hot-reload in the editor. I can literally watch the red and green diffs appear in real-time.

3. The "Test-Driven" Loop
The biggest gotcha with automated refactoring is the "it looks right but doesn't run" syndrome. I've integrated a loop where Claude is required to run my test suite after every major change.

claude "Refactor the UserStore to use a Map instead of an Array for O(1) lookups. After the change, run `npm test` and if it fails, fix the breaking changes automatically."

Config Tips for Stability
Bold bullet lists for my setup:

• .claudignore: Essential. I add node_modules, .git, and build artifacts. If Claude tries to index your dist folder, it wastes tokens and gets confused by compiled code.
• Terminal Integration: I use the integrated terminal in VS Code (Ctrl+) so I can switch between the Claude CLI and my code view instantly. * **Git Branching**: Never run Claude Code on main. I create a refactor/ai-cleanup branch. If it goes off the rails, a git reset --hard` is faster than trying to prompt it back to sanity.

The main friction point is that Claude Code can sometimes be too aggressive, deleting comments or changing naming conventions you actually liked. To mitigate this, I've found that telling it to "preserve all JSDoc comments and avoid changing variable names unless they are objectively misleading" saves me about 15 minutes of manual cleanup per session.

Compared to the standard "copy-paste from chat" workflow, this is a massive leap. I'm spending less time moving text and more time reviewing the logic of the refactor.