Spec-driven development is a requirements discipline, not a tooling trend

Spec-driven development means writing a short, structured description of what software must do, covering behaviour, interfaces, constraints and acceptance criteria, before code is written or generated, and treating it as the source of truth. With AI coding agents in the loop it stops being optional: an agent will build exactly what was asked, including the parts nobody thought to ask about.

What changed

For decades, vague requirements were rescued by people. A senior engineer would read a two-line ticket, recall a conversation from last quarter, and build the right thing anyway. That tacit translation was invisible and enormously valuable.

An AI agent does not attend last quarter's meeting. Give it an ambiguous instruction and it will produce confident, plausible code that resolves the ambiguity in whatever way is statistically likely, which is rarely the way your business needs. The bottleneck has moved from writing code to stating intent.

What a useful spec contains

A spec is not a 40-page requirements document. For most features it fits on one or two pages, organised around seven questions.

• Purpose: why does this exist, and which user problem does it solve? For example, let account managers see unpaid invoices without asking finance.
• Behaviour: what must happen, in plain statements. For example, show invoices more than 30 days overdue, newest first.
• Interfaces: the inputs, outputs and contracts, such as an API schema, an event payload or the fields on a screen.
• Constraints: security, performance, compliance and cost. For example, read-only, no personal data beyond the customer name, responses under 500 ms.
• Edge cases: what happens when things are missing or wrong, such as a customer with no SAP account or a partial payment.
• Acceptance criteria: testable statements that tell you it is done, and that become automated tests.
• Out of scope: what you are deliberately not building, such as payment collection from this screen.

The last item matters more than it looks. Agents are generous; without an explicit boundary they will helpfully build features you then have to secure, test and support.

How it fits the delivery workflow

• Specify. Product and engineering write the spec together. Disagreements surface here, where they cost minutes.
• Review. Architecture, security and the owning team review the spec, not the code. This is the cheapest security review you will ever run.
• Plan and decompose. Break the spec into tasks small enough to verify independently, for humans and agents alike.
• Generate and implement. Engineers and agents build against the spec; acceptance criteria become tests first.
• Verify against the spec. Review asks whether the work satisfies the spec, not whether it looks reasonable.
• Keep the spec alive. When behaviour changes, the spec changes in the same pull request. A stale spec is worse than none.

How it differs from what you already do

• Test-driven development starts from tests. Spec-driven development starts one level up, and tests are derived from its acceptance criteria.
• User stories describe a need. A spec adds the interfaces, constraints and edge cases a story leaves out.
• Design documents often describe how something will be built. A spec is primarily about what will be built, and what will not.

Adopting it without bureaucracy

The failure mode is obvious: specs become forms, forms become theatre, and engineers route around them. Three habits prevent that.

• Size the spec to the risk. A copy change needs a sentence. A payment flow needs two pages.
• Store specs beside the code, in the repository, as Markdown or an API schema, versioned with the code they describe.
• Measure rework, not compliance. Track how often written or generated code is rejected for misunderstanding requirements. If specs are working, that number falls.

How Webneuron works

Our delivery model begins with discovery and architecture before build, the same principle at programme scale. Within our pods, specs live in the repository and acceptance criteria drive our QA automation. If you are introducing AI coding tools and want quality to rise rather than fall, a discovery call is a good place to start.

Frequently asked questions

What is spec-driven development? A practice where a structured specification of behaviour, interfaces, constraints and acceptance criteria is written before code and treated as the source of truth.

Why does spec-driven development matter for AI coding tools? AI agents implement instructions literally. A clear spec removes ambiguity, so generated code matches business intent and needs less rework.

Is spec-driven development the same as test-driven development? No. TDD starts from tests; spec-driven development starts from the specification, and tests are derived from its acceptance criteria.

How long should a software specification be? As short as the risk allows. Simple changes need a sentence; complex or regulated features may need one or two pages.