How to make large structural changes safely. As in earlier chapters, the quoted prompts are real, with links to the resulting PRs where public.
Write the plan, let the agent implement it¶
Refactors that stalled for years because they were too tedious are now a plan file away. Write (or dictate) the plan, let the agent implement it — it will very likely work and pass the tests. Then the real question is yours to answer: is the new structure actually better, and worth the churn? A passing refactor you discard still taught you something cheap.
Example refactors¶
Restructuring files and breaking up modules:
This still looks complex, I think because the machinery and options sit in the same file. Reevaluate the locations of items in _options.py and _options_set.py - and maybe we even need a new options?.py?
— nox#1144
Removing a dependency or a long-dead workaround:
Launch an opus agent to make a PR to move off of build.util.project_wheel_metadata in a worktree.
Launch a agent to remove WORKAROUND_ENABLING_ROLLBACK_OF_PR3068 in a worktree, making a PR
Other classics: swapping click for argparse, converting decorators to fixtures, language migrations (JavaScript → TypeScript, see Repetitive work), and packaging a webapp properly.
Safety nets make refactoring possible¶
A solid test suite, linters, and a type checker are what let the agent (and you) trust a large change; the refactor is only as safe as the checks it must pass. This pays forward, too: simpler, better-structured code is easier for the AI to work on next time, just as it is for humans.
For changes too large for one PR, stage them. Multi-phase changes that failed by hand — like a two-phase framework upgrade — can succeed with an agent because each phase gets verified and fixed before the next, instead of one giant leap. Splitting also makes review humane:
Let’s break out into 5 other PRs, and reduce this PR to just the remaining item. Feel free to use subagents in worktrees. Edit the description of this one when done.
— iminuit#1145 through #1149
Working in parallel¶
Nothing stops you from running several refactors at once, in separate clones
or git worktree checkouts — the prompts above do exactly that. Harnesses
can manage worktrees for their subagents; you review the resulting PRs one
at a time.
Know your git¶
Big refactors mean rebases, force-pushes, history rewriting, and the occasional reflog rescue. You must know these well enough to direct the agent or do them yourself — harnesses are (sensibly) shy about history manipulation, but will do it when asked clearly:
Let’s commit, rebase, then force-push
Let’s gitignore .venv folders, and rewrite history to remove them (oops!)
History is part of the deliverable, too:
Can we restructure the history to tell a story?
Spare subscription time? Point it at cleanups¶
If you have agent capacity left at the end of a billing cycle, aim it at the backlog: hunt for simplifications and bugs, or compare the documentation against the implementation.
Sure, let’s do safe stuff and cleanup. Break into PRs as needed, use opus agents.