How to Use Cline to Refactor Legacy Code Safely
Cline is an open-source AI coding agent that runs as a VS Code extension, reads your files, proposes edits, and can run terminal commands after you approve each one. On a legacy module, its value is not writing new code fast; it is reading 2,000 lines quickly and telling you which parts are dead. You still decide what gets deleted.
The setup matters more than the prompts. A fresh branch, a covered module, and a bounded task produce merges you can defend in review.
What do you need before Cline touches a legacy file?
A test that runs in one command. If the module has no tests, write a characterization test first: call the main public function with a couple of inputs, store the output, commit it. That baseline catches the silent behavior changes an agent will otherwise slip in.
Then a branch, an API key (Anthropic, OpenAI or a local model), and a repo the agent can read without 200MB of build artifacts. Add the build and vendor folders to the ignore file; Cline’s context has a cost and reading junk slows every step.
What is plan mode for and when do you use it?
In plan mode Cline reads and reasons without editing files. Use it for exactly three things on a refactor: mapping the call graph, listing what a file’s functions actually do, and naming the smallest safe change.
A prompt that works: “Read src/billing/legacy_charge.py and every file importing it. Do not edit. List each function, its side effects, and which ones have no remaining callers.” You get a map. You read the map. Only then do you switch to act mode.
How do you run the refactor in reviewable steps?
Small steps, commit between them:
- Delete dead code identified in plan mode. Run tests. Commit.
- Rename one function at a time, using Cline’s project-wide rename. Run tests, commit.
- Extract one behavior into a tested function. Run tests, commit.
- Update call sites. Run tests, commit.
Each commit under ~150 lines. When a step fails tests, revert that commit alone instead of debugging an agent’s five-file change.
Why do agent refactors break builds?
Three recurring causes. It edits a generated file, and the next build overwrites the change. It updates some call sites but not string-based references, like dynamically imported module names. Or it reformats unrelated lines, which hides the actual change in review.
Guard against the third by telling Cline explicitly: “Change only the lines required; do not reformat or reflow existing code.” And check the diff for a generated folder before accepting.
Approve the terminal command, read the output. Auto-approve on shell commands in a legacy repo is how people lose a database.
What does Cline cost?
Cline itself is free and open source; you pay the model provider. On an Anthropic key, a careful refactor of a 2,000-line module with plan mode first usually lands in the low single-digit dollars, which is mostly input tokens for file reads. Budgets can be set in the extension to stop runaway loops.
An alternative path is a subscription editor like Cursor, which bundles model access and is easier to approve for a team. Continue.dev is the better pick if you must run a fully local model for compliance reasons.
Who should not use it
Teams without version control discipline, codebases where a single command deploys to production, and anyone who wants a hands-off tool. Cline pauses for every file write and every command by default; if that interrupts your flow, the approvals are the feature you are paying for in review time.
Quick Summary
- Cline is a free, open-source VS Code agent that reads files and runs commands with your approval.
- Write a characterization test before the first edit; that is the safety net.
- Plan mode first, then act mode in commits under 150 lines.
- Tell it not to reformat existing lines, or the diff becomes unreadable.
- Costs are model tokens only; a bounded refactor of a 2,000-line module is typically a few dollars.
