I used to ask the agent for “a clean refactor of this module” and get a 40-file PR that touched naming, folder layout, hooks, and tests in one swing. CI was green. I still couldn’t review it.

Green doesn’t mean reviewable. An agent-driven refactor is useful only if a human can answer “what changed and why?” in under ten minutes. Here’s the process I use so the model does the mechanical work without turning the PR into a archaeology dig.

The failure mode: one prompt, one mega-diff

The ask that blows up:

Refactor BillingForm and related helpers. Clean up naming, extract hooks, align with our patterns, update tests.

What lands:

Renames across 12 files

A new hooks folder

Test rewrites that assert the same behavior with different structure

A drive-by import sort and a “while I was here” type tweak

None of that is wrong in isolation. Together it is unreviewable. You can’t tell which hunk is the real refactor and which is noise. Reviewers rubber-stamp or reject the whole thing.…