Spec-first, spec-anchored, spec-as-source: the three levels of spec-driven development
The three levels of spec-driven development describe what happens to the spec after the code is merged. Spec-first: the spec is written to build one change, then archived or left alone. Spec-anchored: the spec is kept and updated, so it always says what the system does now. Spec-as-source: the spec is the only thing people edit, and the code is generated from it. Almost all practice is spec-first — in public repositories, 81.5% of spec files were committed once and never changed. Spec-anchored is where the real work, and the drift, begins. Spec-as-source has worked for small components pinned down by large test suites, and is otherwise still an experiment. Below are the levels on one example, which tools sit where, what each level costs, what has been tried at the third, and how to choose.
All SDD approaches and definitions I’ve found are spec-first, but not all strive to be spec-anchored or spec-as-source. And often it’s left vague or totally open what the spec maintenance strategy over time is meant to be.
— Birgitta Böckeler, martinfowler.com, October 2025
The three levels
The names come from Böckeler’s look at three spec-driven tools in 2025. Spec Kit’s documentation now uses them too: “One overview of SDD tooling frames that lifecycle in three levels” (Spec Kit).
| Level | What happens to the spec after the merge |
|---|---|
| Spec-first | Nothing: it served the change and is archived or left as it was |
| Spec-anchored | It is kept and updated with every change, so it describes the system as it is |
| Spec-as-source | It is the only thing people edit; the code is regenerated from it, and nobody edits the code |
The levels build on each other. Every spec-driven workflow starts spec-first; the question is whether the spec stays useful once the change is done.
One change at each level
The payment reminder from the customer portal used across this site. Version 1 of its spec said a reminder goes out for “every open invoice”; months later, a change request (CR-10) added part payments, and the finance lead decided that partly paid invoices get a reminder too. What happens to the spec at each level:
| Level | When the change arrives |
|---|---|
| Spec-first | Version 1 sits in an archive folder. The change gets its own new spec, and what the reminder does now is in the code and the tests |
| Spec-anchored | Version 1 is edited into version 2 in place; the history keeps version 1 |
| Spec-as-source | Version 2 is edited, the reminder code is regenerated from it, and the tests decide whether the result is accepted |
The whole change, from request to version 2, is in the spec-driven development example.
Which tools sit where
As each tool’s documentation described it on 23 October 2026:
| Tool | What it does with specs after the merge |
|---|---|
| Spec Kit | No default. It names three models — flow-back, flow-forward and living spec — and leaves the choice to the team |
| OpenSpec | Spec-anchored with a change record: current specs per capability, and each change merged into them and moved to an archive |
| Kiro | A spec per feature in .kiro/specs/; the largest practice study describes it as keeping “a living spec for each feature” |
| Tessl | In its 2025 beta, exploring spec-as-source: one spec per code file, and the code marked “GENERATED FROM SPEC - DO NOT EDIT” |
A spec.md and plan mode |
Spec-first, unless you decide otherwise |
Spec Kit’s three models are the most useful vocabulary for the choice. Flow-forward treats each
finished feature folder as a record that never changes; a new requirement gets a new folder.
Living spec keeps spec.md as the contract, updated first, with the plan and tasks derived from
it. Flow-back lets the spec, plan, tasks and code all inform each other after delivery. In Spec
Kit’s words: “None is the default, and none is required by Spec Kit.”
OpenSpec builds the anchored level into the tool: “Specs are the source of truth — they describe how your system currently behaves”, and when a change is archived, “its deltas merge cleanly into the source of truth” (OpenSpec). How the tools compare beyond this is in Spec Kit vs OpenSpec vs BMAD.
Where practice actually is
The largest study of spec-driven development in practice collected 470,795 spec files from 73,030 public repositories. “81.5% of spec files have a single recorded commit.” The 21 practitioners it interviewed kept specs in three ways: some “maintained a living spec, retained and updated as the system changed”; some kept “an accumulated change record, committing a new spec to the record for each change”; and a few “discarded specs after implementation”. The split is telling: “Tool users were divided across the three practices, whereas most tool makers kept living specs” (Agarwal et al., 2026, preprint).
A single commit is not a failure in itself. A spec written for one change is supposed to stop changing when the change is done, and in OpenSpec repositories archived change specs outnumber current capability specs about three to one (19,067 to 6,644) because every change adds a file. The study warns against reading too much into that count. What matters is whether anyone mistakes an old change spec for a description of the system now.
Spec-first: the default, and its trap
Spec-first is the right level for most changes: a bug fix, a one-off feature, anything nobody will need to read about later. The spec does its job when the agent builds from it and the reviewer checks the code against it.
The trap is the old spec that looks current. One commenter, on keeping old specs in the repository: “Claude will find old stuff and treat it as canon” (r/ClaudeCode, 2026). Three ways out:
- Delete or archive change specs after the merge, somewhere the agent does not read by default, and keep the decisions in a decision log.
- Keep them as a record on purpose — Spec Kit’s flow-forward. Its documented tradeoff is duplication: “Related decisions can be spread across multiple feature directories.”
- Say which it is. One commenter’s rule: “Basically draw a line between what needs to be kept up to date and what should not be” (r/ClaudeCode, 2026).
Spec-anchored: where the work starts
A living spec is the level most people mean when they say the spec is “the source of truth”. It is also where spec drift begins, because now the spec has to change every time the behaviour does. Spec Kit names the risk plainly: “The main risk is silent divergence. If the team changes lower-level artifacts without reflecting the decision back into spec.md, future contributors may not know which artifact to trust.”
Drew Breunig, who shipped a library as a spec with no code, describes the usual path: “The spec gets written, it gets implemented, it gets released. Is the spec updated? No.” And the leak that is hardest to see: “Bug reports and hotfixes that go straight into code or tests need to be captured and rolled into the spec” (dbreunig.com, March 2026). Some teams give up on it. One OpenSpec user: “I enjoy the OpenSpec format but I think maintaining the main specs is not worth it. I’ve stopped doing it entirely and just archive directly after implementation” (Hacker News, 2026).
Others run checks: an agent that compares specs with the code every night or in every pull request. The practice study adds the limit of those checks: they “can show that code and spec disagree, but not which is wrong.” That decision belongs to a person, and it is a decision worth recording. Why specs and code part ways, and how to catch it, is in what spec drift is.
Spec-as-source: what has been tried
- Tessl generated one code file per spec in its 2025 beta. Böckeler, trying it, saw the limits even at that scale: “Even at this low abstraction level I have seen the non-determinism in action though, when I generated code multiple times from the same spec.” Tessl’s own expert panel concluded that “we’re not at spec-centric yet, but spec-assisted is table stakes” (Tessl, vendor, 2025).
- StrongDM released Attractor, its coding agent, as a repository that “contains no code at all—just three markdown files describing the spec for the software in meticulous detail” (Simon Willison, February 2026). Its software factory checks the result against end-to-end scenarios, “often stored outside the codebase (similar to a ‘holdout’ set in model training)” (StrongDM, vendor).
- Breunig’s whenwords was a small library shipped as a markdown spec and about 750 conformance tests, to be built by whatever agent you use. His lesson: “a spec doesn’t really work until it’s implemented.”
- In research, a team at Meta recovered specs from 72 vibe-coded projects and had a second agent rebuild each one from the spec alone. “Multiple independent regenerations achieve a high mean regeneration score of 5.06 out of 6.0 while remaining diverse in their details” (Paltenghi and Chandra, 2026, preprint). A file system generated from specs, and evolved by patching the specs, “demonstrates equivalent level of correctness to that of a manually-coded baseline across hundreds of regression tests” (Liu et al., ACM Transactions on Storage, 2026). A Swedish thesis in which three models built the same module from one spec found that all passed the unit tests, but that poor reproducibility and the risk of technical debt limited practical use, and concluded that spec-as-source still needs human oversight (Abdulnoor and Bygde, KTH, 2026).
The pattern: spec-as-source has worked where a large executable test suite pins the behaviour down — 750 conformance tests, hundreds of regression tests, a held-out set of scenarios. In those cases the tests carry as much of the source as the spec does. And the same spec does not give the same code twice, which matters as soon as anyone has to review or debug it. One commenter: “If you want to go all in on specs, you must fully commit to allowing the AI to regenerate the codebase from scratch at any point. I’m an AI optimist, but this is a laughable stance with current tools” (Hacker News, 2025).
Böckeler sees an older parallel in model-driven development, where models were the source and generators wrote the code. She wonders whether spec-as-source, “and even spec-anchoring, might end up with the downsides of both MDD and LLMs: Inflexibility and non-determinism.”
How to choose a level
| Situation | Level |
|---|---|
| A one-off change nobody will read about later | Spec-first; archive or delete the spec after the merge |
| Each change is a separate decision you may have to show later | Spec-first with a kept record (Spec Kit flow-forward, OpenSpec’s archive) |
| Several people or agents need to know what the system does now | Spec-anchored, with someone responsible for updating the spec |
| A small, well-bounded component with a large conformance suite | Spec-as-source is worth an experiment |
Whichever you choose, write it down where everyone, and every agent, will see it. Spec Kit’s advice: “document the convention in your project constitution or team onboarding notes so future contributors know how to handle changes.” The levels can differ by area — “A project can even use different models in different areas, as long as contributors know which one applies.” For Claude Code, the two workable choices and where to record them are in spec-driven development with Claude Code.
Where Specroot fits
This is the problem Specroot works on: keeping a spec current after the merge — what the system is supposed to do now, what changed, and who decided — in a form the people who have to agree can read. Specroot for teams using AI coding agents.
Read next
- What is spec drift? — Spec drift is the gap between what a specification says and what was built, planned or agreed from it. Why it happens, how to detect it, how to stop it.
- What is spec-driven development? — Spec-driven development (SDD) means writing the spec before an AI coding agent writes the code: how it works, an example, the tools, and the criticism.
- How to track changes to requirements: versions and history — How to track changes to requirements: requirement, document and baseline versions, what a history needs, and how to keep it in Word, Confluence, Jira and git.