Spec-Driven Development

Most rework comes from building the wrong thing correctly. A spec is the cheapest place to discover that.

A specification says what, not how. Inputs, outputs, behaviour at the edges, what happens on failure, and what is explicitly out of scope. If a reader can implement it two materially different ways and both satisfy the document, it is not finished.

Acceptance criteria make "done" checkable. Given-When-Then — the Gherkin format from behaviour-driven development — forces each criterion into a testable shape: given some state, when something happens, then this is observably true. Criteria written as "the feature should work well" cannot be verified and will be argued about at review.

Non-goals are the highest-value section and the one people skip. Writing "this does not handle offline editing" closes a discussion before it opens and stops scope expanding to fill the review meeting.

An architecture decision record (ADR) captures one decision: the context, the options, what was chosen, and the consequences accepted. Its value shows up months later, when someone asks why a strange choice was made — the conclusion alone ages badly, because the reader cannot tell whether the constraints still hold.

Contract-first applies the same idea to interfaces: agree the schema before either side implements. Consumers can build against a mock immediately, and the interface gets designed rather than emerging from whatever the handler happened to return.

A spike is the escape hatch. When you genuinely cannot specify something because of an unknown, timebox an experiment to answer the one question, throw the code away, and then write the spec. The failure mode is a spike that quietly becomes the implementation.

The spec is not a contract you must not change. It is a tool for finding disagreement early. Discovering mid-build that it was wrong is the process working.