Spec-Driven Development: The Promise and the Blind Spots
Writing the spec before the agent codes is the right instinct. But a Markdown spec can't be verified and knows nothing of the existing system.
October 13, 2026 · 6 min read
I like spec-driven development. I’d rather say so up front, because the rest of this piece is about its gaps, and gaps are always easier to point at than to fill.
For years the spec was the neglected document of software projects. Written at kickoff, skimmed once, never updated. The code quietly became the only reference, and anyone who wanted to know what the system did had to read it line by line.
Coding agents changed the economics. When an agent writes several hundred lines in a few minutes, the quality of what you ask for decides almost everything. So teams started writing the intent, the requirements and the plan first, then letting the agent implement inside that frame. Tools such as GitHub Spec Kit and Kiro gave the idea a name and a shape, and plenty of teams now run it with templates of their own.
That instinct matches a conviction we’ve held at Lyriks from the start. Code is where the implementation lives. The source of truth is what you meant to build.
So where does the practice fall short? In three places, and a hotel booking engine shows all three.
Credit where it’s due
Before the criticism, the part that works. A written spec forces a conversation that used to happen too late. Product, engineering and whoever owns the business rules have to agree on wording before the agent starts. The agent gets context instead of a one-line prompt. Reviewers get a reference point. If your team adopted spec-driven development this year, you probably saw fewer “that’s not what I asked for” moments, and that alone is worth keeping.
Free text resists checking
Most specs in this style are Markdown files. Readable, versionable, easy to hand to an agent. Also free-form prose.
Consider a hotel group’s cancellation policy, written the way most specs get written: “Guests on a flexible rate can cancel free of charge up to 48 hours before arrival.” Clear enough to a person. Now ask whether the code follows it. Forty-eight hours before what, exactly? Check-in time at 3 p.m., or midnight on the arrival date? In the hotel’s time zone or the guest’s? Someone has to interpret the sentence, and that someone is either a human who doesn’t have time to review every change or an LLM that interprets probabilistically. Ask the LLM twice and you may get two readings.
The verification gap is well documented. Sonar’s State of Code Developer Survey (January 2026, more than 1,100 developers) found that 96% of developers don’t fully trust AI-generated code, while only 48% always verify it before committing. A better spec improves what the agent receives. On its own it does little to close that gap, because nobody can mechanically check code against a paragraph.
Two specs, one guest, one bill
A single spec can be perfectly clear. Trouble starts when they pile up.
Say the revenue team writes a second spec for a new prepaid rate. Prepaid bookings are charged in full at reservation and are non-refundable. Sensible. Then the loyalty team writes a third. Gold members can cancel any booking free of charge up to 24 hours before arrival. Also sensible.
Each document is internally consistent. Put them side by side and a Gold member holding a prepaid booking becomes a puzzle. If they cancel 30 hours before arrival, is the charge refunded? The prepaid spec says no. The loyalty spec says yes. The billing rule now contradicts itself, and an agent implementing either spec will faithfully build its half of the contradiction.
Markdown files have no idea they disagree. Nothing in the text connects the prepaid charge rule to the loyalty cancellation rule. Somebody has to read both, at the right moment, and notice. With three specs that might happen. With three hundred it won’t.
Your hotel already has rules
Spec-driven development feels most natural on a new project. Most teams don’t work on new projects. They work on a booking engine that has been in production for years, carrying rules nobody wrote down. A grace period for no-shows added after a complaint. A special case for group bookings. A cutoff that differs for one property because of a local regulation.
Writing a spec for a change without the spec of what already exists is like drawing a new wing without the plans of the building. The agent implements the new cancellation rule perfectly and quietly breaks the group-booking exception, because that exception lived only in a conditional deep inside a file called legacy_rates.py.
Asking an LLM to document the existing system usually produces dozens of pages of Markdown. It reads well. It is also disconnected from the code it describes, impossible to verify, and out of date by the next merge. You end up with a documented system that is still out of your hands.
Turning prose into a model
Here is how we approach those three gaps at Lyriks. Two design choices do most of the work.
First, the spec is a structured model rather than a text file. Features, user journeys, actions, business rules, screens, objects, attributes and invariants are explicit elements in a graph database. Each one links back to its source, whether that is the code that implements it, the ticket that requested it or the page that described it. For an existing booking engine, the model is built by reverse specification, by reading the code. The no-show grace period and the group exception show up as rules, linked to the lines that implement them, in a form a product owner can read and correct.
Second, verification is handled by a deterministic engine instead of a language model. The engine is built on graph rewriting and developed in-house. Same question, same answer.
Put those together and each gap narrows.
- The 48-hour rule becomes an explicit rule the code is checked against, and every release is sorted into compliant, addition, omission or regression.
- The prepaid and loyalty specs are compared on the model before anyone writes code, and their contradiction comes back as a decision to make.
- New specs land on a map of the existing engine, so the group exception is visible before it gets broken.
The agent keeps its role. The validated spec goes to it over MCP, with rules and sources, and every gap found goes back until all rules hold. The Product page walks through the full loop.
Six months from now
Keep writing specs first. The teams that popularized the practice did everyone a favor, and going back to one-line prompts would be a step backward. The open questions all come after the spec is written. Can anyone show that the code matches it? Do specs notice each other? Do they know about the system they land on?
For the hotel, there is a simple test. Half a year from now, can someone answer “what exactly happens when a Gold member cancels a prepaid room 30 hours out?” by pointing at a rule, its source and the code that applies it? If the answer still depends on who you ask, and on which day, the spec has more work to do.
We write about questions of method like this one regularly. If that’s your kind of reading, the newsletter is the easiest way to get the next piece, and earlier articles are on the blog.