Refactoring With Claude Code
I maintain WP-AutoInsight solo. It runs on 3,000+ WordPress sites, and it went from version 3.3 to 4.0 with a lot of the code written alongside Claude Code. Somewhere in that stretch, I noticed a familiar pattern: tasks that used to take one prompt started taking four, and the agent began breaking things into files it had no business touching.
That pattern has a name, and the fix is old. When your coding agent slows down and starts introducing bugs in unrelated places, the codebase needs refactoring, and the safest way to do it with Claude Code is plan mode plus an isolated git worktree plus tests that pass before and after. The rest of this post is about how I run that, and why AI-heavy codebases hit this wall faster than human-only ones.
Why does AI-written code degrade faster?
AI-generated code accumulates structural debt faster than human-written code, mainly through volume and imitation. An agent produces in a week what a developer used to write in a month, and every new file it writes copies the patterns it finds in the existing ones. If there's a duplicated component in the repo, the agent duplicates it again. If error handling is inconsistent, the new code is inconsistent in the same ways, plus a few new ones.
Humans do this too. We always have. Codebases drift toward mess through normal use, whether the hands on the keyboard are biological or not. The difference is speed. A human team takes a year to bury a bad abstraction under enough layers that nobody wants to touch it. An agent working daily gets there in a couple of months.
There's a second effect that matters more for anyone doing serious work with agents: context. A messy codebase costs the model more tokens to understand. The same feature request forces it to read five near-identical files instead of one shared component, hold all of them in context, and guess which one is canonical. It guesses wrong sometimes. That's where the bugs in "code you didn't touch" come from. I wrote about keeping agent context lean in my Claude Code WordPress workflows, and refactoring is the structural version of the same idea.
Strip the ceremony and refactoring is just this: changing the structure of code without changing its behavior. Same inputs, same outputs, cleaner internals. That definition hasn't moved since Fowler wrote it down in 1999. What changed is who benefits. In 2026, the main beneficiary of a clean structure is the agent that has to read it two hundred times a day.
When should you refactor an AI-assisted codebase?
The signal is agent performance, and you should act on it earlier than feels necessary. There's no line count or calendar date that triggers a refactor. What you need to watch for is the behavior:
- The agent takes noticeably longer on tasks that used to be quick
- Bugs appear in files the agent wasn't asked to modify
- You keep applying the same fix in more than one place
- The agent's explanations of the codebase start contradicting each other between sessions
Any one of those on its own can be noise. Two of them together means drift.
The temptation is to push through. You're mid-feature, the deadline is real, and stopping to reorganize folders feels like procrastination with extra steps. On a specific client in Canada, I recall the owner postponing the refactor of a critical WordPress plugin for almost a year, and then complaining that the team wasn’t refactoring fast enough when everything broke with a WP update.
Refactoring is routine maintenance, the same category as updating dependencies. The teams that get hurt are the ones who treat it as an emergency instead of a routine, because by the time it feels like an emergency, the agent has already spent weeks copying the broken patterns into new code. If you've shipped something fast in vibe coding mode, budget the cleanup pass before the next feature, while the mess is still shallow.
How to refactor with Claude Code
Here's the setup I use, a workflow that works is isolation, planning, and verification, in that order:
Start in a worktree. claude --worktree refactor-name creates an isolated checkout on its own branch and opens the session inside it. Your main branch stays untouched, and you can keep shipping fixes from the original directory while the refactor runs. If the refactor goes sideways, you delete the worktree and lose nothing.
Plan before touching anything. Plan mode (Shift+Tab) forces Claude to read the codebase and produce a written plan before it edits a single file. For refactoring, this step is mandatory. I tell it what to restructure and, importantly, why. "Consolidate the four content-generation classes because every provider change currently requires four edits" gives the model the goal, so when the plan has to make a judgment call, it makes the one aligned with the reason. Then I actually read the plan. In my experience, the plans are usually solid on the first pass, but "usually" is doing work in that sentence, and a bad refactoring plan executed confidently is worse than no refactor at all. My PACREF prompt structure covers how I frame these requests so the context and constraints are explicit instead of implied.
Tests before and after. This is non-negotiable. Refactoring means behavior doesn't change, and the only proof of that is a test suite that passes before the work starts and passes after it ends. If the code doesn't have tests, writing them is step zero of the refactor, and yes, that makes the job bigger. But without tests, all you have is a rewrite and a prayer.
One refactor at a time. Parallel feature work is fine. Parallel refactors are how you end up with two branches that each reorganized the same module differently, and a merge conflict that reads like a hostage negotiation.
On effort settings: refactoring is exactly the kind of task where you want the model thinking hard, so use the highest reasoning effort your plan allows and let it take its time. This runs fine as a background task while you work on something else.
What this looks like on WordPress projects
WordPress codebases hit this wall in specific places, usually that initial plugin file that became a 3,000-line junk drawer. The site keeps working, so nothing forces the cleanup, and the agent keeps stacking code on the pile.
The refactors that pay off fastest on WordPress projects are consolidation refactors: one settings class instead of five, one API client instead of a wp_remote_post call copy-pasted into every feature, hooks registered in one place instead of scattered across twenty files. Each of those cuts the number of files an agent has to read to make a change, which cuts tokens, time, and the odds of a wrong guess. It's the same reason AI demos fail in production: structure that nobody notices in week one decides everything by month six.
So when do you actually schedule it?
Treat it as a recurring task, monthly or per release, whichever comes first. Have Claude Code scan the repository, flag what drifted, and run one scoped refactor in a worktree with tests. Estimate two to six hours of wall-clock time per pass on a mid-sized plugin or theme, most of it unattended. That's cheap insurance against the alternative, which is an agent that gets a little dumber every sprint until you can't ship without babysitting it.
The agents write the code now. Keeping the code in a shape they can work with is the part that still needs a human with opinions.
If your team shipped a lot of AI-written code fast and the velocity is now going the wrong way, auditing that codebase and setting up a sustainable agent workflow is exactly the kind of consulting I do.