Build1 publisher3 min readPublished
Committing the spec leaves an ambiguous copy of the feature beside a precise one
A dev.to post groups spec-driven development frameworks by what they do with the markdown once the LLM has written the code, and argues for deleting it on the grounds that code is the less ambiguous description.
The Engineer · Build desk
What happened
- A dev.to post narrows "specs" to the markdown files that spec-driven development writes before an LLM implements a change, excluding OpenAPI, AsyncAPI and README-style docs about what a system does today.
- It sorts what frameworks do with those files into three dispositions: deleted, kept and stale, or kept and updated, with an archive folder counted as the stale case rather than a fourth option.
- The author ran Spec Kit, OpenSpec and BMad Method on the same starting prompt for one feature, followed each suggested workflow, and counted the markdown lines produced beyond one-time setup files.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- cost Choosing the kept-and-updated disposition buys a maintenance job that recurs on every change, and no test suite or linter will tell a team when it has been skipped.
- exposure Once a stale spec is committed, the next agent gathering repo context can read it as current, because nothing in the tree ranks markdown below the code it produced.
- decision Teams adopting a hybrid framework have to decide which specs count as high level before the first feature merges, since that line is what splits maintained files from discarded ones.
- constraint One developer, one prompt and one feature per framework limits what the comparison can settle about default spec volume in anyone else's repo.
"Kept and updated" is the only one of the three dispositions that promises the spec still describes the system, and nothing in a repository enforces the promise [3]. CI fails when code and tests disagree. Nothing in CI reads the markdown. So staying in sync is a manual chore repeated on every change, and the post treats moving specs into an `archive/` folder as the same category as leaving them stale [3].
Two of the three dispositions leave a file in the repo [1]. The post's argument is that choosing between them is downstream of a question that usually goes unasked: whether to commit the spec at all [5]. Hybrid setups do not escape it; they just split the repo into high level specs that are maintained and feature branch specs that are discarded or archived [4].
The case for deleting rests on precision. The post's example is "bi-weekly", which means both twice a week and every two weeks [6]. Before the code exists, that ambiguity is unavoidable. After it exists, the code has to satisfy a strict syntax to be valid, so it says one thing [6]. "Duplication also means competing sources of truth," the post says. "If the code says one thing and the spec says another, who decides what is correct?" [7]
The strongest objection is intent, and the post concedes it before answering: specs do capture why a change exists better than the code does [8]. It then names five places intent already lives next to the code [2]: commit messages and pull request descriptions, comments on non-obvious code with links to JIRA tickets or GitHub issues, unit and integration and end-to-end tests, Architecture Decision Records for decisions that should not be casually reversed, and README.md and other markdown that gives humans and LLMs context [8]. Whatever is left over, the post argues, mostly repeats what the code already shows [10].
The empirical part is thinner than the argument. The author ran Spec Kit, OpenSpec and the BMad Method, gave each the same starting prompt to add one feature, followed each framework's suggested workflow, and counted the lines of markdown produced, excluding one-time project setup files [9]. The published text stops before the counts appear [11]. For counts gathered that way to say anything about your repo, your feature has to be about the size of the one they prompted for, and you have to run the default workflow without trimming its steps. One run per framework measures what a default generates, not a spread.
In my view the delete option is right for a team where every change lands through a reviewed pull request, because the reasoning is already in the PR description and the constraints are already in tests. The context that would flip it is a codebase where the spec is read by someone who does not read code. The post's own evidence on the frameworks is one developer, one prompt and one feature each [9].
What to watch
- Whether Spec Kit, OpenSpec or BMad Method add a delete-or-archive step to the default workflow instead of leaving the disposition to the developer.
- Publication of the per-framework markdown line counts the post says it measured, which would let readers compare against their own feature size.
- Whether coding agents start ranking committed code above committed markdown when both describe the same feature.