Member-only story
Spec-Driven Development — Breaking Changes Start in the Spec: Requirements Semver, Blast-Radius Analysis and a Spec Changelog
When an agent regenerates code from a spec, one word changes the contract. Requirements semver, a diff checklist and a changelog template
Swapping “may” for “must” in a single sentence of a spec looks like an editorial fix. Once the code is regenerated, though, it can break three integrations, two of which no documentation describes. This applies to teams where an agent regenerates code from the spec, because regeneration makes the spec the carrier of intent, while the knowledge of who reads which field stays outside it. By the end, you’ll be able to classify such a change with requirements semver, work out its blast radius and set a compatibility window, and you’ll leave with a SPEC_CHANGELOG.md template and a spec diff review checklist.
Let’s take a scene composed of typical cases rather than one incident. In a user profile, the requirement read: “The customer may send the marketing consent status.” Someone changes one word, the diff is one line long, the review takes a minute. The agent regenerates the code along with the tests, the tests pass, and the deploy goes to production.
