Why You Should Not Commit Your Specs

When discussing software development, it is common for new methodologies or ideas to emerge and gain traction before fading away. One such idea gaining popularity recently is Spec Driven Development (SDD), which involves writing a specification before any code is written. The specification is then used as input for a language model (LLM) to generate the code.

This article explores the afterlife of spec files after they have been implemented, focusing on three different approaches to handling them: deleted, stale, or kept and updated.

Committing specs alongside code introduces ambiguity, as English is inherently ambiguous, while code is precise. While specs may capture the intent behind a change better than code, this should not be a reason to keep the spec files. Instead, developers have other ways to convey intent, such as commit messages, pull request descriptions, comments, unit tests, architecture decision records, and README files.

Committing specs also leads to duplication, as much of the information is already present in the code. This duplication creates competing sources of truth, making it hard to determine which is correct. Additionally, committing specs results in information overload, as developers have to sift through large amounts of markdown files, which is not practical.

Lastly, specs can become outdated quickly, leading to problems with language models that try to interpret stale specs, causing confusion and burning tokens.