You know the feeling. You’re deep in a codebase, hunting for the spot where some obscure requirement was implemented. The spec is a PDF that lives in a folder nobody opens. The comments in the code are either missing or lied. The only way to verify coverage is a manual audit that everyone dreads. It’s like trying to prove a contract was fulfilled by reading tea leaves.
I’ve been there. I’ve written specs that are better when I quote them directly inside the implementation. Not as a comment that says “see spec section 4.2” but as an actual verbatim pullquote. That quote becomes a living bridge between the requirement and the code. When the spec changes, the quote lights up like a neon sign: “Update me, right here.”
This isn’t a theory. It’s a practice I’ve formalized into a small tool called Great Spectations. It’s not a massive framework. It’s a handful of scripts that check that every requirement is quoted somewhere in the codebase, and that every quote hasn’t drifted from the canonical spec. It’s the diff against your own documentation. And it’s trivial.
Let’s be honest: most teams treat specs as artifacts. They’re written once, approved, then archived. The code evolves, the spec decays, and six months later nobody knows what the original intent was. The result is technical debt, rework, and finger-pointing. The best spec is the one that verifies itself.
Here’s the provocative angle: treat the spec as a dependency. Just like you pin a library version, you pin the spec quote. You import it. You test against it. The spec becomes a first-class citizen of your codebase, not a guest that shows up late and leaves early.
Now, the twist: most people think specs are too rigid to embed. They’re afraid of “tying the code to a document.” But the opposite is true. When you quote the spec, the code becomes more flexible because you can see exactly what’s required and what’s optional. You can refactor with confidence. You can trace the lineage of every decision. The spec becomes a scaffold, not a cage.
Specifications that aren’t quoted are just suggestions.
I built this for myself on a project called CLN, where spec changes were frequent. My hacky scripts saved me hours of grep-and-compare. Then I realized: every team that ships a spec-based product suffers the same pain. Why not share the formalization?
So here it is. Great Spectations. It’s simple. It’s opinionated. It works. If you’re a developer, a tech lead, or a project manager who’s tired of spec-code misalignment, give it a try. The first time you see a spec quote change and the corresponding code line highlighted, you’ll feel the relief I felt.
Your specs don’t have to be dead weight. They can be executable. They can be living. Stop treating them like separate documents. Start embedding them.
FAQ
Q: Doesn't embedding spec quotes make the code messy and hard to read?
A: No more than comments. In fact, a well-placed quote is clearer than a vague comment. The tool can be configured to ignore quotes in non-essential areas, and the coverage check ensures you don't over-quote. The messiness of a decaying spec is far worse.
Q: What's the practical benefit for a team that already uses automated tests?
A: Tests verify behavior, not intent. A spec quote tells you what the requirement was, not just whether the code passes a test. When a test fails, you need to know if the spec changed or the code broke. Embedded quotes give you that context instantly.
Q: Isn't this just a fancy way of writing comments?
A: Comments are free-form and often stale. Spec quotes are verifiable. They are checked against the canonical spec. If the spec updates, the quote becomes mismatched and the tool flags it. It's a dependency, not a decoration. That's the difference.