Spec-Driven Development: koniec vibe codingu? Jak specyfikacje zmieniają pracę z AI
SDD inverts the order of work: the specification becomes the source of truth first, then AI generates the code. It is a spectrum, not a single method: spec-first, spec-anchored and spec-as-source — the latter meaning "code you never touch". It addresses four real limits of AI agents: task scope, missing feature context, missing project knowledge and unchecked autonomy. The workflow has six stages: Constitution, Specify, Clarify, Plan, Tasks, Implement. Sixty to eighty percent of generated code being usable after review already counts as success — SDD gives you structure, not magic. It does not replace engineers; it moves their work towards architecture and validation.
The vibe coding problem: code that looks right but solves a different problem
You know the scenario. You describe a feature to an AI agent. You get back a few hundred lines that compile, pass the linter and look professional at first glance. An hour later you realise it solves a slightly different problem than the one you had in mind.
On a prototype that costs you half a day. On a production system where several teams ship in parallel, that kind of drift turns into weeks of rewriting and quiet technical debt that only surfaces at the next change.
The problem is not the model's capability. It is how we use it. We treat agents like search engines you can throw a keyword at — but they are literal pair programmers: they build what we wrote, not what we meant. Spec-driven development (SDD) is an attempt to close that gap.
What is spec-driven development?
Spec-driven development is an approach where the team first defines what it is building and why — system behaviour, constraints, interfaces and acceptance criteria — and only then writes the implementation. The specification stops being a supporting document and becomes the source of truth, for humans and AI agents alike.
The inversion is the point. Traditionally the code is the source of truth and the documentation ages in a folder nobody opens. In SDD the spec is a living artefact: a requirement changes, you update the spec, and the implementation follows. It is, in short, version control for your thinking.
What SDD is not
Three objections are worth defusing straight away. SDD is not about writing bloated documents nobody reads — a good feature spec is usually two pages. It is not waterfall, because the cycle closes at the level of a single feature, not the whole project. And it is not bureaucracy, because every artefact has a specific audience: a human doing a review, or an agent writing the code.
An example that circulates across the industry in various forms makes it concrete. A team is building a notification system. The product manager understands "user preferences" as separate toggles for email, push and SMS. The backend implements a single on/off switch. The frontend assumes preferences will come from the operating system. Nobody did anything wrong — there was simply no shared context. A specification surfaces assumptions like these while agreeing on them costs a few sentences rather than two sprints.
Three levels of SDD — a spectrum, not one method
Much of the confusion around SDD comes from three very different levels of ambition hiding behind one name. Birgitta Böckeler's breakdown on Martin Fowler's blog sorts them out:
- Spec-first — a refined specification is written before the work starts and guides the agent through a specific task. The lightest variant and the easiest way in.
- Spec-anchored — the specification lives on after the task is done and serves as up-to-date documentation while the feature is extended and maintained.
- Spec-as-source — the specification becomes the primary artefact and the developer edits only that. AI generates all the code; tools such as Tessl mark it with a "DO NOT EDIT" warning.
Different tools aim at different points on this spectrum, which is why their promises diverge. For most teams the realistic starting point is spec-first or spec-anchored. Spec-as-source is an experiment today — an interesting one, but risky in production.
Why is SDD showing up now? Four limits of AI agents
Writing specs before code is not a new idea. What is new is that it now has a specific audience. EPAM's analysis organises four agent limitations that a specification genuinely addresses.
1. Task scope and length
Language models hold their quality across changes touching one to three files. At ten or more, consistency starts to break down: names drift apart, logic gets duplicated, integration points are missed. SDD forces decomposition — a feature breaks into user stories, and those into atomic tasks spanning one or two files.
2. Missing feature context
The agent does not know the business requirements, the edge cases or the acceptance criteria. A prompt is ephemeral and dies with the session. A specification and system-design layer stays in the repository — you can come back to it in three months, at the next change to the same feature.
3. Missing project knowledge
Reading a repository is not the same as understanding it. The agent does not know which libraries are approved, which patterns were deliberately abandoned, or what the security requirements are. Worse, old files teach it bad patterns. The answer is a constitution — the written-for-AI equivalent of a senior engineer's first day of onboarding: the stack with versions, naming conventions, architectural decisions, the list of allowed and forbidden dependencies, security requirements.
4. Unchecked autonomy
An agent can hand back a change across fifteen files with no trace of the decisions that led to it. Inside is a mix of good code and quiet bugs, and reviewing that bundle is a lottery. SDD inserts gates: first a spec review, then a plan review, and approval to implement is a separate step.
## Stack
- PHP 8.3, Symfony 7.4 — no additional frameworks
- Tests: PHPUnit; every public endpoint has a functional test
## Conventions
- strict_types=1 in every file, final classes
- No logic in controllers: the action delegates to an application service
- Comments and names in English
## Forbidden
- New dependencies without the tech lead's approval
- Writing files inside a database transaction
- Strings hardcoded in components — translation files only
## Security
- Personal data never in logs
- Every upload: MIME validation, size limit, private diskWhat the SDD workflow looks like in practice
The most popular implementation of the pattern is GitHub Spec Kit. The workflow has six stages:
- Constitution — you write down the project rules that apply to every task.
- Specify — you describe the feature: behaviour, constraints, acceptance criteria. No technical decisions.
- Clarify — the agent asks about gaps and contradictions; this is where unspoken assumptions surface.
- Plan — the technical design appears: modules, contracts, the order of changes.
- Tasks — the plan breaks into atomic tasks, each within reach of a single agent run.
- Implement — the agent executes the tasks and you review increments rather than the whole thing.
Technically Spec Kit is a command-line tool, a set of templates and commands invoked inside the agent. It works with Copilot, Claude Code, Cursor and others. The artefacts are ordinary Markdown files in the repository, so you version and review them like code.
One practical note from our own projects: the quality of the first feature description decides the quality of everything downstream. The more you write about requirements and anti-requirements — what you are deliberately not doing — the fewer corrections you make later.
The tooling landscape: native versus bolted on
The whole industry is converging on one pattern: intent, specification, plan, execution. The difference is how deeply a tool supports it.
Native: GitHub Spec Kit with Copilot, where the commands are a first-class feature; Kiro from AWS, an IDE designed from the ground up around specifications; and Tessl, with the most ambitious spec-as-source vision.
Bolted on but related: Cursor's Plan Mode generates a plan before execution — philosophically similar, technically different. Windsurf bets on its Cascade agent and persistent context without formal specifications. The same goes for the planning modes in Claude Code, Gemini CLI and Amazon Q Developer. Spec Kit can be used with them through community integrations, but without formal verification gates. On the open-source side, the lighter OpenSpec and BMAD are worth knowing.
The conclusion is simple: the pattern is portable. Plain Markdown files in your repository are enough to start, and the choice of tool is a question of the stack you already work in.
On the projects where we started with a spec and a plan, code review stopped being about syntax and started being about architecture. That was the real change — not speed, but what we talk about over the code.
What SDD gets right
It extends the window of safe delegation. Without structure you can sensibly hand an agent ten- to twenty-minute tasks. With a specification and a plan that window grows to multi-hour features at comparable quality.
It shifts work left. More thinking at design time, less cleaning up after implementation. That is the simplest lever on technical debt we know of: the cheapest debt is the debt you never took on.
It changes the developer's role. From writing code towards designing systems and validating them. Code review focuses on architecture and conformance to the spec, not on typos and style.
It makes specifications a first-class artefact. Versioned, testable, validated in CI/CD. Documentation stops drifting away from the code, because it is an input to the process rather than its by-product.
There is also a benefit our clients feel most directly: a good specification means a predictable estimate. When the scope is written down and agreed before the start, the number of surprises drops on both sides — which is why we treat ideation and discovery as a separate project phase rather than a formality before signing a contract.
Where SDD falls short — an honest list of limits
Vendor material is promotional and forum criticism is one-sided. The truth is less comfortable: SDD has several real weaknesses and they are worth knowing before you adopt it.
Tension with Agile
Agile taught us to welcome change and to value working software over comprehensive documentation. SDD asks you to write detailed requirements before the first line of code. The counter-argument is reasonable: modern SDD assumes iterative specifications, so you update the spec and regenerate the implementation as a lightweight change process. But the open questions remain — how to reconcile detail with iteration speed, and whether the spec will not become yet another document that drifts from the code.
Walls of markdown
Today's tools generate a lot of verbose, repetitive documents to review. Paradoxically it is often easier to read the code itself than to wade through several screens of specification. The practical takeaway: keep the specification as light as it can be while staying unambiguous. If nobody reads it, it is not a source of truth — it is theatre.
A false sense of control
Despite detailed specifications, templates and checklists, agents can still ignore an instruction or misread the context. A large context window is no guarantee the model will actually use it. A specification reduces the risk; it does not eliminate it — and that distinction matters when someone is budgeting for review.
A mismatch with the size of the problem
The full SDD process on a small bugfix is using a cannon on a sparrow. Even on medium-sized features the overhead is noticeable. The industry has no good answer to the question of how large a task has to be before SDD actually pays off — for now it is a matter of a team's judgement.
A lesson from history: model-driven development
In the early 2000s MDD promised exactly the same thing: high-level models, automatic code generation, focus on intent rather than syntax. In business applications it failed — wrong levels of abstraction, tooling overhead, rigidity. Language models remove some of those obstacles, because you no longer need parsable domain-specific languages or custom generators. But we also lose what MDD did well: the validation and consistency of structured, machine-readable specifications. The question worth asking before you adopt it: are we taking the worst of both worlds — MDD's rigidity and the non-determinism of language models?
Semantic diffusion
The word "spec" is already being used as a synonym for "a detailed prompt". Without precise definitions, SDD risks becoming another buzzword that means everything and nothing. That is why the definitions and the three-level spectrum are at the top of this article, not at the bottom.
Realistic expectations
Three things vendors mention most quietly. Writing a sensible project constitution is the work of an experienced engineer and many iterations — a junior will not do it in a day. Sixty to eighty percent of generated code being usable after review already counts as success; the rest needs polishing, usually in edge cases and integrations. And the tools themselves are young: Spec Kit is still in early versions, so formats and workflows will keep changing.
The value of SDD lies in structure and enforced clarity, not in magic. Two people following the same process will get wildly different results, and the difference will be engineering judgement.
The most expensive projects we have ever taken over from someone else did not have a problem with the code. They had a problem with nobody being able to say what the code was supposed to do.
Who SDD makes sense for, and who it does not
It makes sense for teams already working with agents, for enterprise and brownfield projects with compliance requirements, for organisations running many services and APIs, and for platform teams building shared contracts for others.
It does not make sense — yet — for solo projects and quick prototypes; vibe coding is enough there and it is faster. It also does not make sense in teams without settled conventions: you cannot write the constitution of a project where there is no agreement on how files are named. Standards first, then SDD.
Whose job is this anyway?
SDD tutorials ask you to define product goals and user stories, which opens an uncomfortable question: is that a developer's job or a product manager's? In practice it sits between the two roles, which is why SDD tends to be organisationally hard rather than technically hard. For a software house that is an opportunity — most of the value is created exactly at the seam between product and engineering.
How we approach this at Midapt
We do not adopt SDD as a certified methodology. We take three things from it that work on client projects. We write the specification and the plan before implementation on MVP projects, because that is where avoiding a rewrite pays back fastest. We treat the constitution as a codification of team standards: written once, it serves every task and every agent. And we run review in two stages — conformance to the spec first, implementation details second.
[To be completed by the team: one concrete example from a project, anonymised if needed, with a number along the lines of "X% fewer corrections after review".]
Najczęstsze pytania o Spec-Driven Development
Vibe coding is a loop: prompt, code, corrections. SDD is: specification, plan, tasks, code. Vibe coding works for prototypes, SDD for production systems.
Not if the specification is a living document updated along with the project. The workflow is iterative at the level of individual features, not the whole project.
No. Spec Kit is the most popular tool, but the pattern itself — constitution, specification, plan, tasks — can be implemented with plain Markdown files and any agent.
For a single feature: from an hour to a day. A project constitution takes several iterations spread over weeks. That time comes back as fewer corrections after review.
Yes, and it is one of the best scenarios. A constitution lets you encode existing conventions that an agent cannot infer from the repository alone.
No. It moves review up a level: you check conformance to the architecture and the specification instead of typos and style.
A similar promise with different technology. MDD required formal models and code generators; SDD uses natural language and language models. It loses some of MDD validation but gains flexibility — success depends on team discipline, not on the tool.
On small bugfixes, hotfixes and simple changes the process overhead outweighs the benefit. A plain prompt with good context is enough there.
In summary: pragmatism over dogma
SDD is neither a silver bullet nor a fad without substance. It is a set of habits that age well. Five principles worth bringing to it:
- Apply spec-first thinking to complex, production-critical work, not to everything.
- Keep specifications as light as possible while they stay clear.
- Stay iterative — small, reviewable changes instead of one big design up front.
- Treat specifications as a tool, not a religion.
- Learn from the history of model-driven development instead of repeating it.
The AI revolution in software development is real. But a revolution does not mean abandoning everything software engineering has taught us — it means applying those lessons with new tools.
Wondering how to bring AI agents into your development process safely? Let's talk about your case.