Size the spec to the consequences
In June I wrote a requirements document for a small shop. Nobody made me write any of it.
It asked for microservices. An API gateway. A message queue and an event driven pipeline. Eighty percent coverage, end to end tests, visual regression, a deployment pipeline, rate limiting, key rotation.
What shipped over three days was a backend and a frontend on a hobby host, an image service and a catalogue sync. Zero tests. Then I never touched it again.
Six days later I started a shop for a real business which ran for ten months and nearly five hundred commits. Same stack, opposite outcome. The difference was not architecture, and working out what it was gave me the thing I now use on every project.
The two lines
Every spec I write now opens with these, answered concretely, before anything else:
Who is waiting for this. A person, not a market. Someone I can message when it is ready. If I cannot name them, I am not building, I am entertaining myself, and that is allowed but it should be labelled.
What happens if it does not exist. Nothing is a valid answer. It just sets the budget at a weekend.
Those two lines settle most of what the rest of the document was trying to guess at: scale, quality bar, how much it can cost, whether it needs to survive me.
Sizing the quality bar
Then I set the bar explicitly, as a decision rather than a gap I quietly feel bad about:
- Money paths and anything that computes what someone is owed: tests, always, whatever the project is. This is the one I never flex.
- Anything a stranger can reach: input validation and an error path that fails loudly.
- Everything else, on a short lived project: no tests, written down as a choice, with the sentence "if this survives three months, add them".
A written decision not to test something is a completely different artefact from an untested thing. One of them you can revisit. The other is just rot.
Why the enterprise spec was actively harmful
Not because it was ambitious. Because it was unmeetable, and an unmeetable document stops being a constraint on day one.
I did not build eighty percent of it and feel bad. I ignored all of it immediately and felt nothing, because at some level I knew when I wrote it that it was decoration. That teaches you that documents can be ignored, and the next document, the one that mattered, gets the same treatment.
Who I was writing it for
An imagined reviewer. Some senior engineer looking over my shoulder who would be satisfied by the word microservices and unimpressed by a monolith.
That reviewer does not exist and has cost me more weekends than any real one. The honest version of that document would have been four lines. It took me a summer to be able to write four lines instead of four pages.