Spec-driven development

Guesses compound. A missing edge case here and an assumed default there, and the shipped result drifts from what was needed. Writing the spec forces the hard cases into view while they are still cheap to fix. It also gives a plain test at the end: does the finished feature behave as the spec says in each state?

1. Write the problem and the out-of-scope list first.
2. Describe behaviour as User story items a person could check.
3. List the unhappy paths, such as failed payment or empty results. See Edge case.
4. Keep the spec next to the work, in the issue or the repository.
5. Change the spec before changing the code when a decision changes.

A spec, short for specification, is a written description of what a feature must do. In this approach the spec comes first and the code follows it. That matters more now that AI coding agents write much of the code. An agent given a vague title fills every gap with a guess. An agent given a clear spec has something to build against and something to be checked against.

A useful spec is short and specific. It usually holds:

• The problem and who has it.
• What is out of scope.
• User stories that can be tested.
• Every state the feature can be in, including empty, loading, error and cancelled.
• The data it reads and writes.
• How success will be checked.

• Describing how to build it instead of what it should do.
• A long document nobody rereads.
• Never updating it after launch.