Spec-driven development: the fix for messy AI-generated code
Spec-driven development means writing a clear, versioned specification, covering goals, requirements, constraints and acceptance criteria, before asking an AI coding agent to build anything. The agent then works through a loop of specify, plan, break into tasks and implement, checking its work against the spec. It emerged in 2025 as a response to messy vibe-coded projects, with tools such as GitHub’s open-source Spec Kit and AWS’s Kiro IDE built around it.
What is spec-driven development?
With vibe coding, you describe what you want and let an AI agent write code, then keep prompting until it works. That is fast for prototypes but tends to produce code that drifts from the original intent, invents details and becomes hard to maintain as a project grows. Spec-driven development adds discipline: you write down what the software must do and how success will be checked, and the agent builds against that document. The specification becomes the source of truth; code is the output.
How does the workflow work?
Many teams also keep a short “constitution” or principles file with rules that apply to every change, such as coding standards, security requirements and libraries to use or avoid.
Which tools support it?
| Tool | What it is | Good for |
|---|---|---|
| GitHub Spec Kit | Open-source, MIT-licensed CLI with slash commands for specify, plan, tasks and implement | Teams that want a portable process across agents |
| AWS Kiro | An agentic IDE built around requirements, design and tasks documents | Teams that want specs built into the editor, especially on AWS |
| Claude Code skills and project files | Reusable workflows and CLAUDE.md guidance | Teams already using Claude Code |
| Plain Markdown | Spec files in the repository, used with any agent | Anyone starting without new tools |
GitHub open-sourced Spec Kit in September 2025, and Kiro launched in July 2025, according to The BCMS guide to spec-driven development. Spec Kit works with many agents, including Claude Code, GitHub Copilot and Gemini CLI. You do not need either tool to start; the method works with Markdown files and discipline.
How do you write a good spec?
- State the goal: One paragraph on the problem, the users and the outcome.
- List requirements: Short, testable statements, for example “users can reset their password by email”.
- Add constraints: Security, performance, accessibility, technology choices and what not to change.
- Define acceptance criteria: How you will know each requirement is met, ideally as tests.
- Note open questions: Decisions still to make, so the agent does not invent answers.
- Review with a person: A product owner or engineer approves the spec before building.
What are the benefits?
- Agents produce code closer to intent on the first pass
- Reviews compare code with the spec, not with memory
- New team members and agents can understand the project quickly
- Changes are deliberate: update the spec, then the code
- Specs double as documentation
What does a spec look like in practice?
A team adding password reset to a web app writes a one-page spec. The goal: let users regain access without contacting support. Requirements: users request a reset by email; the link works once and expires after 30 minutes; the new password must meet existing rules. Constraints: reuse the current email service, no changes to the login page layout, log every reset. Acceptance criteria: an email arrives within a minute; an expired link shows a clear message; tests cover each case. The agent produces a plan and seven tasks, implements them one by one and writes tests that map to each criterion. Review takes minutes because reviewers compare the change with a short document rather than a long chat history.
How does it change the team’s work?
Product managers and designers spend more time writing clear requirements and acceptance criteria; engineers spend more time on design decisions and review, and less on boilerplate. That shift suits cross-functional teams: the spec becomes the shared language between product, design, engineering and the AI agents doing much of the typing.
What are the caveats?
- Writing specs takes time; it pays off on anything beyond a quick prototype
- Over-detailed specs can become a new form of waterfall
- Specs go stale if decisions are not written back
- It does not replace code review, testing or security checks
How UIUX Studio helps
We combine product design and engineering to write specs that agents and people can build from, and use spec-driven workflows in client delivery. Talk to our product engineering and product design teams. For agent set-up, see our Claude Code beginner’s guide.
Frequently asked questions
What is spec-driven development?
Writing a clear specification first and having AI agents build and verify code against it.
Is it the same as waterfall?
No. Specs are small and iterative, updated as decisions change.
Do I need GitHub Spec Kit or Kiro?
No. They help, but Markdown spec files work with any agent.
Does it work for designers and product managers?
Yes. Writing requirements and acceptance criteria is a product skill.
When is it overkill?
For throwaway prototypes and quick experiments.