Spec first or build first with a coding agent
A customer asks for a new screen. The usual next step is a spec: someone writes it, three people read it, there’s a meeting, and the spec gets approved. Then engineering builds it, and the first time anyone sees the real thing, half the approvals turn out to mean different things to different people.
With a coding agent that can take a ticket to a reviewed PR, there’s another option. Skip the spec, let the agent build a first version behind a flag, and review the actual screen. I’ve been doing the second one for UI work, and for a lot of features I think it’s the better default. For some it’s clearly the wrong call, and I’ll get to those.
The two options
Spec first. You describe the feature in a doc (or a ticket, or a Figma file), get sign-off, then build. Changing your mind is cheap because nothing exists yet, so you just edit a paragraph.
Where it breaks is the review, because everyone’s signing off on a paragraph. “A board view for bays” reads fine to everyone in the meeting, and each of them pictures a different board. You find out when the code lands, and by then it’s expensive to change.
Build first. You hand the agent the request with no design spec. It builds a working version behind a flag that’s off by default, so nothing changes for anyone. The reviewer turns the flag on for themselves, uses the screen on real data and says what’s wrong, and then you do round two.
Here the downside is cost: a wrong first version is real code you throw away or rework. When a person had to write all of it, that was usually too expensive to try for a screen the team hadn’t agreed on. With an agent doing the build, that’s a lot cheaper. The first passes I’ve watched took the agent a bit under two hours of wall time per round, including its own tests and QA. I think that comes out cheaper than everyone reading the doc, plus the meeting.
A made-up walkthrough
Say you run a scheduling app for repair shops. The day view is a time grid, with technicians down the side and hours across. A few shops ask for a “bay board”, where each column is a service bay and each row is a time slot.
Round one. You give the agent the request and two sentences of context, and no mockup. It builds the bay board as a new layout for the day view, behind a per-device switch in Settings, off by default. When the switch is on, the bay board replaces the day grid for every resource in the shop.
The PR says up front that the design is still open, and it lists the calls the agent made on its own so the reviewer knows what to push back on:
## Review notes
- This is a design first pass. The job chips, the "held until" label
and the bay name under each column are the agent's choices, for
review.
- Out of scope: dragging a job to a new time, splitting one job
across two bays.
## Decided for you (reply on the PR to change)
- Entry point: a switch in Settings, per device, off by default.
The review. The reviewer turns the switch on and uses it for a morning, and the feedback is short: keep the day grid, because most shops still want it. Make the bay board an extra option, and let each shop pick which bays show up on it, per service type.
I doubt anyone would have written that in a spec. The per-service-type idea came up because someone used a real screen with real bookings on it.
Round two. The Settings switch goes away. The day header gets a “Day | Bay board” toggle, and it only appears when the shop has marked at least one service type for the board. The board’s columns are exactly those bays, and the device remembers the last pick.
Round two’s own QA catches something else: on a tablet in portrait, the new toggle pushes the search and filter buttons off the header, so it collapses to one icon below that width. People in a spec meeting don’t open the page on a tablet, so that one would have slipped through too.
Keep the first pass where staff can’t trip over it
One catch: the flag has to actually hide the feature. A related trick for a first pass that lives inside an existing screen is to take the entry point away until launch. If the new views are only reachable with a URL parameter, you can try them in production on a demo account while everyday users never see the button. At launch, you revert the small PR that hid it.
The flag decides whether the feature exists at all, and the config check decides whether this shop has asked for it:
// Made-up example: the entry point stays hidden until launch.
const showBayBoardToggle =
flags.bayBoard && shop.serviceTypes.some((t) => t.onBayBoard);
Where each one wins
| Situation | Better choice | Why |
|---|---|---|
| New screen or layout on existing data | Build first | Reviewers react to a screen far better than to a paragraph |
| Option the customer asked for but can’t describe | Build first | The review produces the real requirement |
| Change you can hide behind a flag and switch off | Build first | A wrong round costs a revert |
| Payments, refunds, anything that moves money | Spec first | A wrong first version can charge someone |
| Data migrations | Spec first | You can’t flag off a column you already dropped |
| Public API or webhook shape | Spec first | Someone else’s code starts depending on round one |
| Anything that can’t sit behind a flag | Spec first | There’s no safe place for a draft to live |
Everything in the bottom half can do damage before anyone reviews it, so write those down first. A flag hides the screen, and it does nothing to stop a bad ledger write or a bad migration from running.
When build-first goes wrong anyway
A few things I’d watch even on the safe side of that table.
Reviewing the code instead of the screen. If the reviewer just reads the diff, you’ve built the thing and still only got spec-level feedback. The review has to happen on the running app, with the flag on, on data that looks like a real customer’s.
Treating round one as the answer. Round one is there so someone can react to it. If it ships as is because it works, you skipped the step that made build-first worth it.
No list of the agent’s choices. Without the “decided for you” section, the reviewer has to guess which details were deliberate, and they’ll probably push back on the wrong things.
Flags that never get removed. Once round two ships and the toggle is the real feature, the old switch and the old code path go, or you end up maintaining two versions of the day view.
What I’d do this week
If you’ve got a spec meeting on the calendar for a UI feature that can sit behind a flag, try swapping it. Give the agent the request, ask for a first pass behind a flag that’s off by default, and ask it to list every design choice it made in the PR. Then spend the meeting slot clicking around the build. Payments and data migrations still get a spec, though.