What is spec-driven development?
Spec-driven development is a way of working with coding agents in which a written specification of behaviour, constraints and acceptance criteria is agreed first, and the agent then uses it to plan, implement and verify the code.
A vague prompt forces a coding agent to guess at dozens of requirements, and wrong guesses tend to surface late. Spec-driven development moves those decisions into a document before any code is written. GitHub's announcement of its open-source Spec Kit (September 2025) frames the spec as a contract for how the code should behave, and the source of truth the agent uses to generate, test and validate it.
AWS made the same bet with Kiro, introduced in July 2025 as an agentic IDE built around specs, pitched as a way to take prompt-built prototypes to production.
How the main tools run it
Spec Kit: specify
The developer describes what is being built and why, focusing on user journeys and success criteria, and the agent drafts the detailed spec.
Spec Kit: plan
The developer supplies the stack, architecture and constraints, and the agent writes a technical plan.
Spec Kit: tasks and implement
The agent breaks the spec and plan into small, testable tasks, then works through them while the developer reviews focused changes.
Kiro: requirements
User stories with acceptance criteria written in EARS notation (Easy Approach to Requirements Syntax), which forces edge cases into the open.
Kiro: design and tasks
A design document built from the codebase and the approved requirements, then ordered tasks, each linked back to a requirement.
Why it suits coding agents
The GitHub post argues that models are good at pattern completion but cannot read minds, so the gap between a prompt and the intended behaviour is where agents go wrong. A spec also gives security, compliance and design constraints a place the agent will actually read, instead of a wiki it never sees, and changing course becomes a matter of editing the spec and regenerating the plan.
The labs reached a similar conclusion inside their own harnesses. Anthropic's post on harness design (March 2026) has the generator and evaluator agree a sprint contract, what "done" means, before any code is written, and its long-running harness work used a feature list with every item marked failing at the start.
Where it falls short
Spec drift
Code changes during review and the spec is not updated, so the next agent run works from an out-of-date contract.
Ceremony on small changes
A three-stage spec for a one-line fix costs more than it saves. The method pays off on features and greenfield work.
Unverifiable criteria
Acceptance criteria that no test or check can confirm leave the agent to judge its own work, which it does generously.
False confidence
A long, tidy spec can hide a wrong assumption. Specs still need review by someone who knows the domain.
How Motiontic's engineers apply it
Motiontic's engineers already start every engagement with a scope document, and spec-driven development extends the same habit to the code: requirements and acceptance checks written down before an agent builds, kept in the repository, and updated in the same change as the code that alters them.
Prompt-first compared with spec-first development
| Prompt-first | Spec-first | |
|---|---|---|
| Where requirements live | In the prompt and the developer's head | In a versioned spec in the repository |
| Edge cases | Found when something breaks | Named in acceptance criteria up front |
| How done is judged | It seems to work | Each task maps to a requirement and a check |
| Changing direction | Re-prompt and hope | Edit the spec, regenerate the plan |
| Fits | Prototypes and small fixes | Features, greenfield builds and legacy rewrites |
Common questions
What is GitHub Spec Kit?
An open-source toolkit from GitHub, announced in September 2025, that adds specify, plan, tasks and implement steps to coding agents such as GitHub Copilot, Claude Code and Gemini CLI.
What is EARS notation?
The Easy Approach to Requirements Syntax, a structured way to write requirements as conditions and responses. Kiro uses it for acceptance criteria so assumptions in a prompt become explicit.
Is spec-driven development the opposite of vibe coding?
Largely, yes. Vibe coding skips reading the code; spec-driven development fixes what the code must do before it exists and checks the result against it. Both GitHub and AWS present specs as the route from prototype to production.
Related
Vibe coding
Prompt, accept, run, repeat: building by results without reading the code.
Sprint contract
Generator and evaluator agree on done before any code is written.
"Done when" criteria
Completion written down as checks before the agent starts, not judged after.
Coding agent
An agent with a shell and a repository: it reads, edits, runs the tests and tries again.
AI product development
New products and major AI features, built from scratch alongside the client's team.
Sources
- GitHub Blog, Spec-driven development with AI: Get started with a new open source toolkit (2025-09-02)
- GitHub, github/spec-kit repository
- Kiro blog, Introducing Kiro (2025-07-14)
- Anthropic, Harness design for long-running application development (2026-03-24)
- Anthropic, Effective harnesses for long-running agents (2025-11-26)
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.