Stop Writing Software Twice: Spec-Driven Development and the End of Rewrites
Why software has always been written twice — once in specifications, again in code — and why that second write is finally going away.
In software development, when done right, we have to write software twice: first, in detailed specifications that explain exactly what the software should do, and then again as code that brings those specifications to life. But here’s a hard truth: it is rarely done right the first time.
The process often breaks down because creating exhaustive specifications is time-consuming, and teams rarely capture all the necessary details upfront. This leads to gaps, assumptions, and costly rework. As a result, software projects often run over budget, miss deadlines, and leave everyone frustrated.
The Hidden Costs of Writing Software Twice
To understand why writing software twice is necessary but rarely done well, let’s break down the two phases:
1. The First Write: Natural Language Specifications
The first time software is written, we’re not writing code at all. It’s creating requirements, user stories, and design documents—written in natural language. This is where teams describe how the software should function, what users can do, and what the experience should be like.
But here’s the problem: no team ever has the luxury of writing all the details. Product managers often have to rush to meet aggressive timelines – some projects don’t even employ professional product managers. They outline the broad strokes, but key features and interactions are missed. As Steve Jobs famously said, “Great products are made by 5,000 small decisions,” but in most projects, we don’t make those decisions upfront. They’re left for developers to interpret later, which leads to the second step.
2. The Second Write: Translating Specifications into Code
Once the specifications are handed off, engineers are responsible for turning those descriptions into functioning code. But when the first “write” is incomplete, developers are forced to use their imagination to fill in the blanks. Assumptions are made, and while engineers may have a good grasp of technology, they may not have the full picture of the product’s vision.
This is where the problems surface:
- Missed details lead to friction: When product teams don’t specify an important feature or use case, developers have to guess or improvise. This often results in functionality that doesn’t meet expectations.
- Assumptions lead to rework: When developers fill in the blanks, they may build features in ways that don’t align with the product vision, causing massive rework later in the project.
- Finger-pointing becomes inevitable: As deadlines slip and budgets overrun, teams shift blame. Product teams call-out engineering for “not getting it,” while engineers point fingers at product for unclear specs.
The result is a cascade of problems that lead to missed timelines, overshot budgets, and unsatisfactory outcomes. The Standish Group’s CHAOS research has tracked for years that the majority of software projects run over budget and miss their delivery dates. A McKinsey study with the University of Oxford found that large IT projects on average run 45% over budget and 7% over time, while delivering 56% less value than predicted — and that 17% of large IT projects go so badly they threaten the very existence of the company.
Clearly, something in this process is broken.
The Practice Now Has a Name
The industry settled on a term for this while most people were arguing about prompts: spec-driven development. Write the requirements, the constraints and the success criteria first. Treat that spec as the source of truth. Let the agent build against it.
GitHub shipped Spec Kit. AWS shipped Kiro. BMAD-METHOD, OpenSpec and Tessl all took a run at it. Martin Fowler has written it up. The convergence is not a coincidence — it is what happens when an entire category discovers the same failure mode at the same time.
And the failure mode is the one described above. Prompt-first tools skip the first write entirely. They go straight to the second one, guessing at every decision the spec never made. Which is fine for a demo and ruinous for a product.
Spec-driven development does not eliminate the first write. It makes the first write the only one that requires human judgment.
The New First Write: Specifications You Can Actually Finish
Here is what changes. The reason nobody wrote complete specifications was never that they didn’t want to — it was that the work was too slow to justify. Weeks of discovery to produce a document that went stale on contact with the first sprint. So teams wrote the broad strokes and left the 5,000 small decisions to be discovered later, one interpretation at a time.
When drafting a specification takes hours instead of months, the arithmetic inverts. You can afford to be exhaustive. Functional requirements, visual design, data model, edge cases — captured before anyone opens an editor, and cheap enough to revise when you learn something.
That last part matters. A specification that can’t be revised cheaply becomes a lie the moment reality arrives. This is the same instinct behind building API-first: get the load-bearing decisions right before anyone writes a screen, and the rest follows.
The New Second Write: Code Generation, Not Translation
Once the specification is complete, the second write stops being a translation problem. It becomes a generation problem. Standard languages — JavaScript, TypeScript, Python. Standard frameworks — React, Next.js. Real code, in the shapes engineers already know, derived from a document that already made every decision.
The difference is not that developers work faster. It’s that they stop doing the part that was never engineering — the mechanical restatement of decisions somebody else already made.
What Changes Downstream
Three things change at once:
- The first write gets finished: When specification work costs hours rather than months, teams can afford to make the small decisions upfront instead of discovering them in review.
- Nobody fills in the blanks: Code generated from a complete spec doesn’t require anyone to guess what the product team meant. The guessing was always where the defects came from.
- Rework stops compounding: Intent and implementation start aligned. What used to be a rewrite becomes an edit to the spec.
The Future of Writing Software: Natural Language
For as long as anyone has shipped software, the job required writing it twice: once in natural language, again in code. That second write was never the valuable part. It was the toll we paid because there was no other road.
This is the move the next generation of AI app builders is organized around: clarity before code. Describe the application as a blueprint, get the architecture right, let the code be generated against it. Not a shortcut around the definition work — a reason to finally do it properly.
There is another way now. Software was always supposed to be written once.
Related Reading
The full guide to the practice: spec-driven development. Why the prompt-first generation skipped this step is covered in vibe coding broke its promise, and what replaces it in what comes after vibe coding.
Frequently Asked Questions
What is spec-driven development? Spec-driven development means writing the requirements, constraints and success criteria before any code is generated, and treating that specification as the source of truth the AI agent builds against. It emerged in 2025 as a direct response to prompt-first workflows that skip the definition step entirely.
How is spec-driven development different from writing a traditional requirements document? The document is the same idea; the economics are not. Traditional specs were expensive enough that teams wrote the broad strokes and discovered the rest in code review. When a specification takes hours instead of months and can be revised cheaply, it becomes worth finishing — and worth keeping current.
Which tools support spec-driven development? GitHub Spec Kit, AWS Kiro, BMAD-METHOD, OpenSpec and Tessl are the named implementations, and Cursor supports a lighter version through rules files. They differ mostly in how tightly the spec is bound to the code — whether it drives generation once, evolves alongside the code, or is the only artifact you edit.
Does spec-driven development slow teams down? It moves the work, it doesn’t add it. The decisions captured in a specification are decisions somebody makes regardless — either deliberately up front, or implicitly by a developer or a model guessing later. The second path is where rework comes from.
What happens to developers if code is generated from specs? The mechanical restatement of somebody else’s decisions goes away. Judgment about architecture, tradeoffs, correctness and what not to build does not. Those were always the parts that required an engineer.
