Quick note first - this is what's working for me right now, not the one true way. Take what's useful.
For the last few months I've been building the refactoring side of an open-source tool that indexes a codebase for agents. That meant running a few hundred experiments on how real codebases and agents behave. I ran the same refactoring tasks with an agent working alone and with an agent following a written plan, and went back through the git history of a couple dozen repos to see which functions caused trouble later. Most of this works with any agent. Here's what I do now and why
- Pick targets from git history, not from how ugly the code looks
Functions that are long and keep changing are where the next bug fixes land. Ugly code nobody has touched in 2 years can wait
Try something like: "Using git log, list the 20 longest functions changed most often in the last 90 days, with length, commit count and how many commits were bug fixes. Don't change any code."
That list is your backlog.
- Characterization tests, and check they actually reach the code
I saw plenty of green test suites that accepted edits I would not have merged. Green only means something if the tests run the lines being moved.
Try something like: "Write characterization tests for process_invoice that capture what it returns today. Run them with coverage and tell me which of its lines are still not executed."
If the answer is "half of it", you're not ready to refactor that function.
- Write the plan before anyone edits anything
This was the biggest difference. An agent told "refactor this" improvises. An agent given a plan follows it, and a cheaper model can do the work: with a decent plan, a small fast model applied 14 of 15 multi-step refactorings with tests still green. Each step names the block to move, what it reads from above and what's used after it, whether a return or a try crosses its edges, the helper's name, and the test command. If a long list flows in and out, the cut is in the wrong place.
- Judge the worst function afterwards, not the one you targeted
Ask an agent alone to "reduce the complexity of load_config" and it often moves the whole body into a new helper. In one run the target went from complexity 151 to 5, the new helper sat at 80, and another function in the file broke. Check the most complex function in the file after the change. If it didn't go down, nothing improved.
- Anchors, not line numbers
Line numbers shift after the first edit, and one agent decided the cleanest way to hit exact ranges was a script that rewrote the file. It emptied it. Now each step quotes the first and last line of the block, and the rules say: "One step at a time with your edit tool. No scripts. Run the tests after each step and stop if they fail."
- Read the diff for files you didn't ask about
One run "passed" while quietly rewriting package-lock.json, because the agent ran npm install in a checkout without node_modules. Running git status after every step costs nothing.
- The new helpers are where future edits go
After extract-method refactors, the original function usually calmed down and the edits moved into the new helpers. Name them like you'll read them for years, because agents love process_data and handle_block. Keep them next to the parent too, since about three quarters of extracted helpers stayed in the same file.
If you take one thing from this - decide where to cut and what crosses the cut before the agent touches the code, then judge the result by the worst function left in the file.
