Why Spec-Driven

Nothing on this page is specific to your project. It describes the method and the tool as they exist, so that the worked example can be read as an application of something already understood.

1.1 Why prompting for code ad-hoc stops working

Ask an AI coding agent to build something and it will. Ask it for a change and it will do that too. The problem is not the quality of any single answer — modern agents write good code. The problem is what happens to everything around the code.

FIGURE 2 — The same work, done two ways. Both lanes end with working code. Only one of them ends with a record of why.

Three failures show up reliably, and all three have the same root cause.

The second change contradicts the first. You asked for de-duplication in March and for "don't drop anything from the primary source" in May. Both requests were reasonable. Nothing checked them against each other, because there was nothing to check them against.

Nobody can review it before it exists. Reviewing generated code means reading generated code. That is slow, it happens after the work is done, and it puts the least technical stakeholder — often the person who actually knows what the thing is for — outside the process entirely.

Handover is a re-explanation. The reasoning behind every decision lived in a conversation. The conversation is gone. The new engineer reads the code and infers intent, which is exactly the situation software engineering has spent forty years trying to escape.

The root cause is that the intent was never written down anywhere durable. Code is a lossy encoding of intent: it tells you what happens, never why, and never what was considered and rejected.

Avoid: treating this as an argument for writing more documentation. Documentation written after the fact goes stale, because nothing depends on it. The point of spec-driven development is that the specification comes first and everything downstream is generated from it — which is what keeps it true.

1.2 The idea — specifications become executable

spec-kit's own framing is worth quoting, because it is sharper than a paraphrase:

Spec-Driven Development flips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them.

"Executable" is doing real work in that sentence. It does not mean the Markdown file runs. It means the specification is the input to the thing that produces the code, rather than a document that sits alongside it and slowly diverges from it. Change the specification and the downstream artifacts are regenerated from it. There is no drift, because there is nothing to drift from.

The method rests on four ideas, which spec-kit states as its core philosophy:

• Intent-driven development, where specifications define the what before the how
• Rich specification creation, using guardrails and organisational principles
• Multi-step refinement, rather than one-shot code generation from a prompt
• Heavy reliance on advanced AI model capabilities for interpreting specifications

The third is the one that does most of the work. A single prompt asks a model to do requirements analysis, architecture, decomposition and implementation simultaneously, and it will attempt all four at once and be mediocre at three of them. Splitting the work into phases, each with its own output and its own review point, is the whole trick.