Why You Should Not Commit Your Specs

Disclaimer

When I say “specs” in this article I mean specs as understood in AI assisted Spec Driven Development: markdown files that describe a change before an LLM implements it.

I am not talking about OpenAPI, AsyncAPI or similar formats.

Context

Spec Driven Development (SDD) is making its way into the mainstream. The idea is not new, but it has been redefined, and when I talk about SDD I only mean its current incarnation:

Before writing any code, a spec is written. The spec is usually written with the help of an LLM. Then the spec is used as input for an LLM, which produces the code.

The spec is usually one or more markdown files with a detailed description of what should be done, created by the developer together with an LLM.

In this post I will look at how popular SDD frameworks implement this idea, with a focus on one question: What happens to the spec once the code is written?

The Afterlife of a Spec

I looked at three SDD frameworks: Spec Kit, OpenSpec and BMad Method.

I wanted to figure out what the frameworks do with spec files once the code is written.

Theoretically, a spec file can only have one of three fates. It is either:

• Deleted
• Kept but never updated
• Kept and updated over time

Each of these frameworks uses a different mix of these three fates, although it is not always clear from reading the docs what their recommended approach is.

Especially when it comes to the problem of outdated specs.

From what I have seen, none of them has a proper answer that isn’t contradicted somewhere else.

And I don’t blame them for not having a proper answer, because I don’t think there is one.

It seems like the discussion quickly gets lost in the details: which specs to keep, which to delete, how to sync them, which tools to use.

To me, this feels like we jumped two steps ahead instead of answering a simple question first: should we commit these specs at all?

My answer is no. Here is why.

Why you should not commit your specs

Ambiguity

English, like every natural language, is ambiguous by nature.

For example, what does “bi-weekly” mean? Does it mean twice a week? Or every two weeks?

The answer is: yes.

Before the code exists, that ambiguity is unavoidable. But once the code is written, we have an unambiguous description of the feature: the code.

Programming languages can be read by humans and machines alike, and they are by nature much more precise than English, since they have to follow a strict syntax to be valid.

Committing the spec next to the code means keeping an ambiguous description of what something does, next to a precise one.

Intent

People will say that specs capture the intent behind a change better than the code does. Sometimes it is hard to tell from the code alone why it exists.

But that is not a reason to commit the spec. We already have plenty of places for intent that live close to the code:

• Commit messages and pull request descriptions
• Comments that explain non-obvious code or other gotchas, with links to JIRA tickets or GitHub issues
• Unit tests, integration tests, E2E tests
• Architecture Decision Records for decisions that should not be casually reversed
• README.md and other markdown files that give humans and LLMs the required context

Duplication

Once the spec is implemented, most of it repeats what is already obvious from the code.

Why maintain something that becomes a burden the moment it is implemented? Why keep the same information twice inside the codebase?

Duplication also means competing sources of truth. If the code says one thing and the spec says another, who decides what is correct?

Information overload

I recently tried out 3 popular SDD frameworks (Spec Kit, OpenSpec, BMad Method), gave them the same starting prompt to add a feature and followed their suggested workflow.

Here are the lines of markdown each one created for that single feature, not counting the one-time project setup files:

Are we still pretending to read all this?

To me a spec has one purpose: to make sure the LLM and the developer share an understanding of what needs to be built.

Once the LLM has ’translated’ this shared understanding into code, and the developer has verified its output, the spec loses its value.

Committing the spec also means committing it to the pull request. 1,773 lines of markdown on top of the actual change leaves the reviewer with two options: skip it, or invest their time actually reading it.

Rot

If every feature that gets implemented leaves behind some type of artifact, these artifacts will pile up quickly. They will also get outdated quickly.

This also leads to problems with LLMs: they inevitably grep one of these files and then get confused as to why the spec is different from the code.

Most models are trained to be careful, so they burn tokens trying to figure out whether the spec is stale or the code is wrong.

To prevent this from happening some SDD frameworks keep a high level ’living spec’ besides these outdated ‘frozen in time’ specs.

But keeping the living spec in sync requires its own set of tools and effort (aka tokens).

Regeneration Fantasy

There is also an underlying notion that suggests that the spec is the source of truth and that the code is just the disposable output.

The specification becomes the primary artifact engineers maintain, and code becomes a derived, regenerable output that AI agents produce from that spec on demand.

— Augment Code, “The Spec as Source of Truth”

The idea is that if you were to delete the whole code of your software system, you could simply regenerate it from your specs.

That notion led Elon Musk to the stupidest take of the year:

Things will move, maybe even by the end of this year, to where you don’t even bother doing coding. The AI just creates the binary directly. And the AI can create a much more efficient binary than can be done by any compiler.

— Elon Musk, xAI all-hands, February 10, 2026 (video at 11:30, original post by xAI)

Great idea. Why generate something both machines and humans understand, when you could generate something only machines understand?

Back to regenerating source code from specs. My main question is simply: Why?

Why would anyone want to regenerate their entire codebase from specs? To switch stacks or languages? Why not use the code and tests you already have? That is exactly what the Bun team did earlier this year when they ported Bun from Zig to Rust.

I truly don’t get it, but maybe I am missing the point.

Summary

I am NOT a fan of committing specs (as SDD understands them) into the codebase.

I am fine with committing the spec while working on the feature, as long as it is deleted before the PR is created. That way it stays in the git history without ending up in the codebase.

Instead of committing your specs, here is what I would do:

• Throw the spec away once the code is merged, or keep it in git history only.

• Make the intent obvious from the code. If that is not possible, add documentation via concise, information-dense markdown files that explain why, not what.

• Make sure your repositories need no external context. A new dev should be able to start working on your project without the help of another dev.

• Don’t cram everything into a central README.md. For example, have a separate markdown file for testing or deployment. High-level markdown files that describe non-obvious features are fine too.

AI Disclosure

I used AI (Claude) to fix my embarrassingly numerous spelling and grammar mistakes.