Agents love refactors the way puppies love shoes. Enthusiastic. Destructive. Convinced they are helping.
The fix is not a smarter model. The fix is a smaller brief. Small diffs win because they keep humans in the loop and keep blast radius tiny.
One concern per PR
This is the whole philosophy.
If the refactor is “rename this module,” the PR renames the module. It does not also invent a new folder structure, clean up unrelated lint, and rewrite comments into a personal essay.
If the refactor is “extract this function,” it extracts the function. It does not modernize the calling convention across the app because the agent got inspired.
One concern. One PR. One review story.
How to brief the agent
Paste a short block that looks like this:
- Goal in one sentence
- Files and directories in scope
- Files that are out of bounds
- Patterns to copy from an existing file
- Definition of done
- Explicit do-not list
Example do-not list:
- Do not add dependencies
- Do not rename symbols outside the goal
- Do not change formatting outside touched lines
- Do not invent helpers for one call site
- Do not update docs unless asked
Agents need fences. Without fences they landscape the whole yard.
Why small diffs are faster in real life
Big bold refactors look efficient in a demo. In a real repo they create review fatigue, merge conflicts, and subtle behavior changes that show up on Thursday.
Small diffs get merged. Merged work compounds. Hero-branch work stagnates.
Five PRs of eighty lines beat one PR of two thousand lines that everyone is afraid to approve.
A concrete pattern for agent refactors
- Ask for a plan only. No edits yet.
- Approve or cut the plan until it is one concern.
- Ask for the patch.
- Run tests and the smallest manual check.
- Merge or reject.
- Only then start the next concern.
Skip step one and you get surprise architecture. Skip step four and you get surprise production.
What to say when the agent proposes a grand redesign
“No. Smaller.”
Sometimes you literally write: “Do the minimum change that compiles and passes tests. Match existing style. Stop after that.”
It feels rude. It works. Politeness is not a substitute for scope control.
Tests are part of the brief
If there are no tests around the area, either add a characterization test first or shrink the refactor until you can reason about it by reading.
Asking an agent to refactor untested critical code in one swing is how you donate your weekend to bisecting.
Order of operations matters:
- Lock behavior with a test or a recorded fixture
- Make the structural change
- Confirm the lock still holds
Review habits that keep you honest
When you review an agent PR, ask:
- Can I explain this diff in one breath?
- Did anything move that is unrelated to the sentence goal?
- Are public APIs stable?
- Is there a new abstraction that only wraps one thing?
- Would I trust this merge right before lunch?
If the answer to the last one is no, the diff is too big or too clever.
A common failure pattern
A vague brief like “clean up auth helpers” is a trap.
Agents reorganize files, invent wrappers, and change error messages that another system parses. Tests pass because the tests mocked the wrong layer. Production complains quietly at first, then loudly through support.
The better brief is specific: move function X to file Y, keep signatures identical, do not touch message strings. Same model. Better leash.
Checklist worth reusing
- One-sentence goal
- Explicit path allowlist
- Do-not-invent rules included
- Tests identified before edits
- Diff size feels reviewable
- Rollback story is obvious
Bottom line
Small diffs are not a lack of ambition. They are how ambition survives contact with a real codebase.
Brief your refactors like you brief a careful junior on a Friday afternoon. Clear scope. Tight leash. Merge the win. Then do the next one. That rhythm beats any dramatic rewrite speech an agent wants to give you.
