Spec-driven development for teams that build with AI

What is spec-driven development?#

Spec-driven development, also called specification-driven development, is a way of building software in which a written, reviewable specification comes before the code and remains the reference for it. The team agrees on requirements and acceptance criteria first; code, tests and later changes are checked against that agreement.

The idea is not new. The reader is. A coding agent follows a precise spec far better than a vague prompt, so AI spec-driven development turns the spec from paperwork into the most direct way to steer what agents build.

Why spec-driven development matters with AI coding agents#

• Agents do what they are told, precisely. An unclear request produces confident, wrong code. A requirement with concrete scenarios produces code you can check.
• Specs scale review. Reviewing a three-line requirement change is faster, and catches more, than reviewing the thousand lines an agent writes from it.
• Specs outlive sessions. A prompt is gone when the session ends. An approved spec is there for the next agent and the next person.
• Specs make tests obvious. Given, When, Then scenarios translate directly into acceptance tests.

The spec-driven development workflow#

1. 01

   Specify

   A person or an agent drafts requirements with IDs and Given, When, Then scenarios, using the terms in the domain glossary.

2. 02

   Review

   The team discusses the proposal node by node in review threads. Agents revise and reply; a person approves.

3. 03

   Publish

   SpecsGraph commits the approved spec to your repository on a spec/ branch and opens a pull request, next to the code.

4. 04

   Build and verify

   Developers and their agents implement against the active requirements. Tests run the scenarios and cite requirement IDs.

5. 05

   Evolve

   When behavior changes, the spec changes first, through another proposal. History and the decision log record why.

How the spec workflow works follows one change through every status, from first draft to merged pull request.

What a good spec looks like#

In SpecsGraph a requirement is a typed node, not a paragraph in a document. It has a stable ID, a short statement and acceptance scenarios written in Gherkin. Here is ORD-12 from the Northwind Commerce sample:

@ORD-12
Feature: Reserve stock for every line item at checkout

  Background:
    Given the Catalog has 5 units of "Trail mug" in stock
    And the Catalog has 1 unit of "Canvas tote" in stock

  Scenario: Every line item gets a reservation
    Given a Customer has a cart with 2 "Trail mug" and 1 "Canvas tote"
    When the Customer starts checkout
    Then a reservation holds 2 "Trail mug" for the order
    And a reservation holds 1 "Canvas tote" for the order
    And the Catalog shows 3 units of "Trail mug" available

  Scenario: Checkout stops when a line item cannot be reserved
    Given a Customer has a cart with 2 "Canvas tote"
    When the Customer starts checkout
    Then no reservation is created for the order
    And the Customer is told that only 1 "Canvas tote" is left
    And payment is not requested

The ID ties the rule to everything around it: the glossary terms it uses, the decision behind it, the commits that implement it and the tests that check it. Requirements and scenarios covers the anatomy in full.

Spec-driven vs. test-driven vs. behavior-driven development#

They fit together. Spec-driven development sets the frame, BDD scenarios make each requirement concrete, and TDD keeps the implementation honest. Domain-driven and behavior-driven foundations explains the methods SpecsGraph builds on.

Living specs, not a document that ages#

The classic objection to specs is that they go stale. That happens when the spec lives apart from the work. In SpecsGraph the spec changes through the same proposals and reviews as the product, agents propose updates when behavior changes, and every approved revision is a Git commit beside the code. The spec keeps pace because keeping it current is part of the workflow, not an extra chore.

It also makes the rest of the team’s work easier: every change becomes traceable from requirement to test, and every agent works from the same shared context.

Start spec-driven development with SpecsGraph#

• Quickstart→Sign in, connect a repository and an agent, and publish your first requirement.
• Requirements and scenarios→Write requirements with stable IDs and Given, When, Then scenarios.
• Start from an existing codebase→Let an agent draft a first spec of software that already runs.
• Working well with agents→Get agents to read the spec first and cite requirement IDs.