What a specification is for.
A spec is not paperwork. It is the cheapest place to be wrong, and the only place an argument is free.
The word specification sounds like bureaucracy — a form to fill in before the real work. That reputation is earned by bad specs, the kind written to be filed rather than read. A good specification is the opposite of paperwork. It is the design itself, captured before it is expensive.
Here is the whole argument for it: every project has a fixed amount of uncertainty that has to be resolved somewhere. You can resolve it early, in a document, where changing your mind costs a sentence. Or you can resolve it late, in the built thing, where changing your mind costs a rebuild. The spec does not add work. It moves the work to the moment it is cheapest to do.
What a spec actually contains
Three things, in plain language. What the thing must do — the behavior, the function, the job it is for. What it is made of — the stack, the cloth, the constraints chosen on purpose rather than inherited by accident. And how you will know it is right — the tests, the measurements, the definition of done that everyone signs before anyone starts.
That last part is the one teams skip, and it is the one that matters most. A definition of done is a promise you make to your future self, when you are tired and the deadline is close and every fiber wants to call it finished. The spec is where your rested, honest self left instructions for your exhausted one.
The spec is where your rested self leaves instructions for your exhausted one.
Specs are not contracts
A spec can change. It should, when you learn something. The point is not to freeze the work but to make the changing visible — so that a decision is a decision, recorded and owned, rather than a quiet drift no one chose. When a spec changes, you can see exactly what you traded and why. When an unspecified project changes, you find out at the end, in the shape of the thing that came out wrong.
We hand the spec back to you regardless of who builds from it. If you take it to your own team, good — it was always yours. That is the test of an honest specification: it is useful to people who are not us.