Spec-driven development needs a living specification
Spec-driven development tools write a spec for each feature. Teams also need a living specification, one shared and reviewed model of the whole system.
On this page
Spec-driven development became a product category in a single year. GitHub open-sourced Spec Kit (opens in a new tab) in September 2025, AWS made Kiro (opens in a new tab) generally available that November, and open-source projects such as OpenSpec (opens in a new tab) and BMAD (opens in a new tab) gathered tens of thousands of GitHub stars each. Behind all of them is an insight that is hard to argue with: a coding agent builds far better from a written, reviewed specification than from a prompt typed into a chat.
Sean Grove of OpenAI made the case at the AI Engineer World's Fair in June 2025. Code, he said in The New Code (opens in a new tab), "is sort of 10 to 20% of the value that you bring. The other 80 to 90% is in structured communication."
But look at what most spec-driven workflows leave behind: a folder of Markdown files for one feature, written just before the code, used to plan the tasks, then set aside when the branch merges. For one developer shipping one change, that is a real step up from vibe coding. For a team that has to keep a system correct for years, with product managers, analysts, testers and several agents working on it at once, it solves the smaller half of the problem.
The larger half is keeping one specification of the whole system true after every change. That is what a living specification is for, and it is the idea SpecsGraph is built around.
Note
In short
Spec-driven development tools write a specification for each feature, which helps one agent build one change. A team also needs a living specification: one shared, structured description of the whole system that people and agents both read, that changes only through review, and that is published to Git beside the code.
What spec-driven development tools do today
Most spec-driven tools run the same loop. You describe a feature. The agent expands it into a specification, then into a technical plan and a list of tasks, and implements the tasks one by one while a person checks each step.
- GitHub Spec Kit names the phases specify, plan, tasks and implement, and keeps project-wide principles in a constitution. Each feature gets its own
spec.md,plan.mdandtasks.md. GitHub describes the spec as "a contract for how your code should behave" that "becomes the source of truth your tools and AI agents use to generate, test, and validate code". - Kiro, from AWS, writes requirements in the EARS format ("THE System SHALL …"), then a design and a task list. Since general availability, it also runs property-based tests that check whether the code matches the spec.
- OpenSpec treats work as changes that are proposed, applied and archived. Archiving a change updates the project's specs, so the next change starts from them. A beta feature called Stores keeps planning in a separate repository that several code repositories can share.
Birgitta Böckeler of Thoughtworks gave the field its vocabulary in October 2025 (opens in a new tab), with three levels of ambition:
- Spec-first. A spec is written first and then used in the AI-assisted workflow.
- Spec-anchored. "The spec is kept even after the task is complete, to continue using it for evolution and maintenance."
- Spec-as-source. The spec is the main source file over time. People edit only the spec, and "the human never touches the code".
Spec Kit's own documentation (opens in a new tab) uses the same three terms, and it is candid about the choice it leaves to you: the toolkit "does not force one artifact maintenance strategy", and "the main risk is silent divergence".
Where a spec per feature falls short
The first field reports are mixed. Böckeler found that on a small bug, Kiro's workflow "was like using a sledgehammer to crack a nut", and admitted: "I'd rather review code than all these markdown files." Colin Eberhardt at Scott Logic put one feature through Spec Kit (opens in a new tab) and got 2,577 lines of Markdown and 3.5 hours of review for 689 lines of code. With his usual iterative approach, he was "around ten times faster". The Thoughtworks Technology Radar (opens in a new tab) rates spec-driven development Assess and notes that some tools "generate lengthy spec files that are hard to review".
None of this makes specifications a bad idea. It shows what happens when a spec is a set of files that one developer generates for one change, and that nobody owns once the change ships. For a team, five problems follow.
- The spec ages at merge. Once the branch merges, nothing ties the spec to the next change. Böckeler notes that it is often "left vague or totally open what the spec maintenance strategy over time is meant to be". A stale spec can be worse than none, because the next agent that finds it will trust it.
- Every feature describes the system again. Each spec restates the parts of the domain it touches, in its own words. After fifty features, the same business rule exists in fifty slightly different versions.
- It stops at the repository. Most systems span several services and repositories. An open Spec Kit issue (opens in a new tab) from September 2026 asks for "a way to represent a product as a logical grouping of multiple repositories/services".
- The people who own the behavior rarely see it. A spec is drafted in one developer's agent session and reviewed, if at all, in a pull request. The product manager, analyst and tester who decide what the system should do seldom read it before the code exists.
- Every agent sees a different picture. Each developer's agent assembles its own context from instruction files, chat history and whatever it finds in the repository. Two agents working on the same rule can hold two versions of it, and both will write confident code. Incomplete context is one reason AI output so often lands near the target instead of on it: "AI solutions that are almost right, but not quite" was the top frustration in Stack Overflow's 2025 Developer Survey (opens in a new tab), named by 66% of developers.
What a living specification is
A living specification is a shared, structured description of how a whole system should behave that stays true as the system changes, because every change to that behavior is agreed in the specification first.
The idea is older than coding agents. Behavior-driven development has long treated executable examples as living documentation, and domain-driven design asks a team to share one ubiquitous language across conversations, documents and code. Thoughtworks' advice for spec-driven teams (opens in a new tab) points the same way: specifications "should still use domain-oriented ubiquitous language to describe business intent", with scenarios written as Given, When, Then.
What is new is the reader. An agent can read the whole specification, cite it and propose a change to it in seconds, so keeping the specification current finally costs less than letting it drift. The case for shared context keeps getting stronger, too. DORA's 2025 AI Capabilities Model (opens in a new tab) found that "connecting AI tools to internal data sources boosts their impact on individual effectiveness and code quality". The Thoughtworks Radar (opens in a new tab) now rates context engineering Adopt and describes context graphs that model institutional reasoning "as structured, queryable data".
A living specification has six properties:
- It covers the whole system. Every bounded context, rule and term the team depends on, not only the part that is changing this week.
- It is structured, not free text. Contexts, use cases, features with Given, When, Then scenarios, glossary terms, roles and contracts are separate entries that refer to each other, so a person or an agent can read one without reading everything.
- It speaks one language. Each term is defined once and used the same way in the scenarios, in review and in the code.
- It changes through review. Anyone, agents included, can propose a change. A person accepts it, and the agreed state is always known.
- It is versioned like code. Changes are drafted on a branch of the specification and merged when they are agreed, with their history kept.
- It lives beside the code. Every agreed change is published to the repository as plain files that anyone can read, diff and test without a special tool, which also keeps each change traceable.
One change, end to end
Here is what that looks like for one change. Northwind Commerce, the sample online store in our docs, has three bounded contexts: Orders takes orders, Billing takes payments and Catalog tracks stock. Customers sometimes pay for items that sold out while they were checking out, so the team decides to reserve stock at checkout.
- Open a workstream. A product manager opens a workstream called "Reserve stock at checkout". It is a branch of the specification, so Main, the agreed version, stays untouched while the team works.
- An agent reads, then proposes. A developer asks a coding agent to draft the change. Over MCP, the agent reads the Orders and Catalog contexts and the glossary, then stages a proposal: a new feature with its scenarios, a new term, reservation, and a change to the checkout use case in Orders.
- The team reviews in threads. The business analyst asks what happens when only part of the cart can be reserved. The tester asks how long a reservation lasts. The agent answers in the threads and stages revised scenarios.
- A person accepts. Each revision is accepted by a person. The agent cannot accept its own work, and the server refuses if it tries.
- Publish. A person publishes the accepted work. SpecsGraph opens a pull request that adds the spec files to the repository, next to the code, and Main moves forward when it merges.
- Build against it. Developers and their agents implement the feature against Main, and the scenarios become its acceptance tests.
The feature the team agreed on reads like this:
Feature: Reserve stock 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
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 requestedThree months later, when the team adds gift cards, the agent that drafts that change starts from these scenarios and from the definition of a reservation, not from a blank page.
A spec per feature or a living specification?
The two are not rivals. A plan and a task list are still a good way to build one change, whether Spec Kit, Kiro or an agent's plan mode writes them. What changes is where the plan starts and where its result goes: it starts from the agreed specification, and when the feature ships, the specification is updated through review instead of being left behind.
Why we are building SpecsGraph
SpecsGraph is our attempt to make the living specification practical for teams that build with AI agents. The problem it starts from is familiar: product intent lives in tickets, business rules in documents, code in Git and test plans in yet another tool, and each agent sees only what fits in its prompt.
- One model of the system. Each project keeps a single typed model, organized the way domain-driven design organizes software: subdomains and bounded contexts, use cases and events, data contracts, and features with Gherkin scenarios, a glossary and roles.
- Branches for change, one agreed Main. Work happens in workstreams. Main changes only when a person publishes agreed work.
- Agents propose, people accept. Agents reach the model through the SpecsGraph MCP server and stage their edits in proposals. Accepting a change, resolving a thread and publishing are human acts, and the server enforces that. It is how people and agents work on one model without stepping on each other.
- The team's words are the spec. Our open-source agent skills ask one question at a time and do not invent detail. Anything a person did not say becomes a question, not a claim.
- No AI of our own. MCP is an open standard, which Anthropic donated (opens in a new tab) to the Linux Foundation's Agentic AI Foundation in December 2025. SpecsGraph works with the agents your team already uses: Claude Code, Cursor, Codex, GitHub Copilot or any other MCP client.
- Plain files in your repository. Published specs are YAML files in your Git repository, readable and diffable without SpecsGraph.
SpecsGraph is early, and we are building it in the open where we can. If your team builds with agents and this problem sounds familiar, see how the workflow works, read our agent skills on GitHub (opens in a new tab), or talk to us on Discord (opens in a new tab).
Questions, answered
A shared, structured description of how a whole system should behave, kept current because every change to that behavior is agreed in it first. People and AI agents read the same specification, changes go through review, and the agreed version is published to Git next to the code.
Spec Kit and Kiro write a specification for one feature, to plan and build that change. A living specification describes the whole system and stays current after each feature ships. The two work well together, because a feature plan can start from the living specification and update it when the feature lands.
No. Files like AGENTS.md tell an agent how to work in a repository, such as its commands, conventions and layout. A living specification says what the system should do. Most teams need both, and AGENTS.md is a good place to tell agents to read the specification before they change behavior.
Not when the specification is living. Waterfall fixes a large document before building starts. A living specification changes in small reviewed steps, as often as the code does, and each change is published beside the code that implements it.
Yes, and most teams will. An agent can read the code and propose the model in small pieces, citing the files it read, while people confirm each piece against what the system should do. A small confirmed model is more useful than a large guessed one.