I Don't Let My Coding Agent Start Until the Spec Is Finished

PassFirst, my passport photo app, was built in a way I had not built anything before. I wrote the complete product and build spec first. Pitch, first market, hard rules, screens, data, pricing, open decisions. Then I handed the spec to a coding agent and reviewed what came back.

This is now how I build. A few things I learned.

The spec is the product decision

Writing “the photo never leaves the device” and “no face editing of any kind” as hard rules at the top of a document is different from deciding it mid-build. Every later choice gets checked against those lines. Anything that needs a server for the photo is out before it is discussed, and I do not have to re-argue it with myself mid-build.

Open decisions go in the spec too

The spec for PassFirst has a section called open decisions: app name and bundle id, prices, guarantee wording, analytics provider, support email. Listing what is not decided is as useful as listing what is. The agent does not guess at those. It stubs them and moves on, and I do not find a made-up price in a paywall three weeks later.

Logic in pure classes, rules in data

Two habits I carried from mobile work that make agent-built code reviewable. Keep logic in plain classes that take plain data, so it is testable without a device. Put rules in data files, so a new passport rule is a new row, not a code change. Both make the diff an agent produces small enough to read.

What stays with me

Taste, scope and the order of work. The agent is fast at the middle of the task. It is bad at knowing which task is the hardest and should go first. That is still my job, and it is the same job it was before.