Aug 29, 2026 · 7 min read
How Do You Refactor an Existing Product's UI With an AI Agent?
The UI refactor process broken into twelve small, gated steps, so an agent can't collapse it into generic redesign slop or break flows nobody documented.
You’ve got a product that works. It was built fast, and it looks it. You point Claude at the whole UI and ask for a redesign, and one of two things happens. Either it comes back generic: rounded cards, a gradient hero, copy that says “Elevate your workflow,” the exact page three other companies shipped this month. Or it goes further than you meant and quietly breaks a flow nobody had written down.
What actually causes it, and what fixes it?
One prompt is being asked to make twelve decisions at once: audience, palette, hierarchy, tone, and more. Nobody’s checking any of them, so the model guesses toward the safest, most average version of “redesign” it’s seen. The fix is to split that one prompt into small steps, each with a written exit condition, so you always know exactly which one to redo when something’s off.
Five rules make that concrete:
| Do this | Because |
|---|---|
| Split “redesign” into decisions you check one at a time | One prompt guessing at all of them lands on the generic default |
| Get sign-off on a mock before touching real code | Mockups are cheap to redo; a shipped rewrite isn’t |
| Merge duplicate components before building the new direction | A new coat on five duplicate buttons is still five components |
| Show mocks to a real user stand-in before you ship | The model’s “looks good” isn’t the same as a buyer’s “I trust this” |
| Reuse the same reviewer personas every round | Fresh personas each round leaves nothing to compare against |
What does the process actually look like?
Twelve steps, one line. Each one only runs once the step before it has a written, checkable exit condition, not a vibe.
This isn’t a hypothetical process. It’s twelve gated skill files, chained together, shipped inside godharness, an open-source tool I built and publish that hands an agent the right process and standards automatically, instead of relying on someone remembering to ask for them.
The gates aren’t the same model marking its own homework: at every panel step, the agent brings you its raw feedback and waits for your reaction before the next step runs. If you never react, the gate never opens.
No existing product yet? This compresses to three steps: write the direction down, build to it, run the same panel on the result. Same mechanism, much shorter chain.
When should you skip this?
If you don’t know your ICP yet, skip the panel steps. A panel judging against personas you made up in the moment produces false confidence instead of an honest “we don’t know.” Go figure out who you’re building for first.
If the product isn’t stable enough to call it a refactor, running the full twelve steps against it is theater. Ship the smaller version, see if anyone cares, then come back.
And skip the whole thing for a one-off landing page or an internal tool three people use. The gates cost calendar time, so spend it where the UI is customer-facing and actually matters.
What does this actually cost?
| Step group | Real cost | Fades? |
|---|---|---|
| Frame + confirm goal | ~30 min, once | No |
| ICP panel, both passes | Hours of your attention | Personas age yearly |
| Mocks + iterate | A few rounds | No, becomes design.md |
| Consolidate + doctor check | Real eng time, once | No, compounds forward |
Running the sub-agents is cheap compared to an engineer’s afternoon. The real cost is your calendar time reacting to what they find, which is exactly the part a better prompt can’t buy you out of.
Related: when agents beat traditional automation and when they don’t, which of your processes are actually worth automating, and rewrite vs. refactor if “existing product” is the fork you’re actually stuck on.
Who actually benefits from this?
The person this actually costs is whoever’s been rubber-stamping whatever the last prompt returned, because arguing with a generic mockup felt like a worse use of an afternoon than just shipping it. This process moves them from approving pixels to approving journeys, which is a better use of their time either way.
If your team’s using AI agents inconsistently on real product work and you want a second read on what’s actually worth building, that’s what an AI & Automation Opportunity Audit is.