Spec-Driven Development: When Agents Write the Code, Humans Write the Spec
AI coding agents changed what a senior engineer's day looks like. Less typing, more deciding. Spec-driven development makes the specification the primary artefact humans produce, and it is how we keep AI-assisted delivery fast without losing control of quality.
By David Kukharchuk
Tech Lead at Mirko
In 2024 we used AI assistants to autocomplete. In 2026 our engineers hand whole features to agents that work in the repository, run the tests and open the pull request. That shift moves the bottleneck from writing code to describing what the code must do. Teams that keep writing vague tickets get vague software, faster. Teams that write specifications get working software, faster. That is the whole idea behind spec-driven development.
Spec-Driven Development (SDD): Specifications as Primary Human Output
What a spec contains
A spec is not a user story with three bullet points. It is a complete description an agent (or a new team member) can implement without asking questions: the behaviour, the data model, the API contract, the error cases, the acceptance tests and the constraints the implementation must respect. We write specs in Markdown next to the code, review them like code and keep them updated when behaviour changes.
Sections every feature spec has
- Goal and non-goals: what the feature is for and what it explicitly does not do.
- Interfaces: API shapes, events, database changes, with examples.
- Behaviour: step-by-step flows including failures and edge cases.
- Acceptance tests: concrete inputs and expected outputs the agent must make pass.
- Constraints: performance, security, compatibility, conventions.
How the loop runs
An engineer writes or updates the spec and the acceptance tests. The agent implements in a sandboxed branch, runs the suite, fixes failures and opens a pull request with its reasoning. The engineer reviews the diff against the spec, not against their imagination of the feature. Review time drops because the reviewer has a reference. The engineering harness around the agent (tools, sandbox, permissions) is the same structure we use for business agents; our Four Classes of Agent Harness video places coding agents in that taxonomy.
Why this is also a quality strategy
Specs double as documentation, onboarding material and evaluation data. When an agent produces the wrong thing, the fix is usually in the spec, and fixing it prevents the same mistake forever. When a client asks what the system does, the answer is in the repository. Our clients on custom software projects started asking for the specs as a deliverable in their own right.
Claude Projects for managers
Spec-driven thinking is not only for engineers. Managers who set up a personal harness in Claude Projects or ChatGPT, with their standards, templates and context attached, get the same effect: consistent, reviewable output instead of ad-hoc chats. We made a short video on how to set that up.
Claude Projects and ChatGPT: A Personal AI Harness for Managers
