For most of the history of software, writing the code was the slow, expensive part, and specification was a formality squeezed in before it. Teams wrote a feature list, started building, and worked out the details as they went. The details were discovered at the speed of development, which was slow enough to correct course.

Coding agents broke that rhythm. A feature that took a week now takes an afternoon. That sounds like pure gain, and mostly it is — but it means a vague brief no longer costs you a slow build. It costs you a fast build of the wrong thing, followed by another fast build of a slightly different wrong thing.

When the code is cheap, the specification is the product. This article covers what a good specification contains today and the parts teams still skip.

Why agents raise the bar for specs

A human developer working from a vague brief does a lot of quiet specification work. They ask questions in standup, notice when a requirement contradicts the data, and make sensible assumptions based on knowing the business.

An agent does some of this, but far less reliably. It fills gaps with plausible guesses, and plausible is the dangerous word: the result looks right, passes a quick click-through, and hides the assumption until a real user hits it.

So the work that used to happen implicitly, inside development, now has to happen explicitly, before it. That is not bureaucracy. It is moving the thinking to where it is still cheap.

What a good spec contains now

1. The outcome, in the user’s words

Not “build an invoice processing module”, but “the accounts team stops re-typing supplier invoices into the ERP”. The outcome tells everyone — human and agent — what to optimise for when the details are ambiguous.

2. The workflow as it really happens

How the work is done today, step by step, written with the people who do it. Including the exceptions: the supplier who sends invoices as photos, the approval that happens by phone, the spreadsheet someone maintains on the side. Most failed projects are not wrong about the main path. They are wrong about the exceptions.

3. The data, measured

Not “we have customer data in the CRM” but what is actually there: how many records, which fields are reliably filled, how many duplicates, which values are free text. Measuring the data before building on it is the cheapest way to avoid a system that works on test data and fails on yours.

4. Every system it touches

For each system the solution reads from or writes to: what the API actually allows, how authentication works, what the rate limits are, and who owns it. Tested, not taken from the vendor’s documentation. The undocumented integration is where projects stall.

5. Edge cases and failure behaviour

What happens when an input is missing, malformed or contradictory? When a downstream system is down? When the AI is not confident? For AI features especially, “hand it to a human” is a legitimate and often the best answer, but it has to be designed.

6. Acceptance criteria you can measure

How everyone will know it works. For ordinary features, that means concrete checks. For AI features, it means an evaluation set: a collection of real cases with known correct answers that the system must handle, which can be re-run every time a prompt or model changes.

7. Decisions and their reasons

Why this architecture, why this model, why not the obvious alternative. Future developers and future agents will both revisit these decisions; writing down the reasons stops them from being relitigated or quietly reversed.

The parts teams still skip

Even teams that write good specs tend to skip three things:

  • Talking to the people who will use it. The person commissioning a system and the person using it every day often describe the work very differently. Both views are needed; the second is the one usually missing.
  • Testing the integrations before committing to a plan. A one-day prototype against the real API often changes the plan more than a week of meetings.
  • Defining how it will be run. Who monitors it, who handles failures, what it costs per month to operate. Running costs are where software’s lifetime cost now sits, and they are easiest to control at design time.

A spec is also an agent’s instructions

One practical benefit of a good specification today: it is directly usable by coding agents. The same documents that align your team — outcome, workflow, data, integrations, edge cases, acceptance criteria — are exactly the context an agent needs to produce code that fits.

Teams that keep the specification in the repository, next to the code, find that agents stay on track much longer, and that new engineers (human or not) get up to speed faster. We describe how we use it in our own workflow in how we build with AI.

How long it should take

For a single workflow with two or three integrations, writing a proper specification takes roughly two to four weeks of elapsed time, most of it spent on interviews, data measurement and integration testing rather than writing. That can feel slow next to an agent that writes code in an afternoon. It is still the fastest route to a system people actually use.

If you would rather have someone else produce it, that is what a discovery phase is for: a fixed-price engagement that ends with a specification and build plan any competent team can deliver from. If you are not sure yet whether anything is worth building, the free AI automation assessment is a two-minute first step.