Spec-driven development, explained
Write what done means before your AI agent writes code. This guide covers what a spec is, what goes in one, and the workflow that turns rough ideas into software that ships right the first time.
A prompt drifts. A spec holds.
What is spec-driven development?
Spec-driven development is a methodology where you write a structured specification before any code, and the spec serves as the source of truth for what gets built. You act as the architect. The agent generates, tests, and validates code against the spec.
The same feature, two ways
Whatever your input leaves out, the agent fills in with a confident guess. Here is the same request as a prompt and as a spec.
The prompt
"add usage limits with email alerts please"
So the agent decides for you:
- When quotas reset (it picks calendar months)
- What happens at the limit (it blocks, you wanted degrade)
- Where limits live (it puts them in the UI)
- What done means (it says done when it compiles)
The spec
REQ-142: Usage-based billing alerts. Goal, context, scope, 4 decisions, 3 edge cases, 4 acceptance criteria.
So you decided, once, in writing:
- Quotas reset on the billing date, not the calendar
- Soft warning at 80%, block at 100%
- Enforced in the metering service, not the UI
- Done means the four criteria pass
Anatomy of a spec
Six parts, each one there because of a failure it prevents. This is the document BrainGrid writes for you in minutes from a plain-language description.
Goal. Customers know before they hit their quota, so usage never surprises them on an invoice.
Context. Metering lives in services/metering. Billing cycles come from Stripe. Email goes through the existing send hook.
Scope. Alerts and enforcement only. No changes to pricing, plans, or the dashboard usage chart.
Decisions. Reset on billing date. Warn at 80%, block at 100%. Enforce in the metering service.
Edge cases. Mid-cycle plan upgrades re-base the quota. Grace period for the free tier. No alert storms on retries.
Acceptance criteria. Alert at 80% and 100%. Resets on rollover. No duplicates per cycle. Enforced server-side.
Goal: the one sentence that says why this exists.
Prevents building the wrong thing well.
Context: what the agent must know about your system before touching it.
Prevents plausible-but-wrong integrations and reinvented wheels.
Scope and non-goals: what this change must not touch.
Prevents collateral damage to features that already work.
Decisions: choices made once, written down, never re-derived.
Prevents drift when sessions restart and context evaporates.
Edge cases: the answers to the clarifying questions.
Prevents the surprises that otherwise show up in production.
Acceptance criteria: testable statements of what done means.
Prevents "done" from being whatever the agent says it is.
The spec-driven cycle
A repeatable loop, not a waterfall. When requirements change, the spec changes first and the implementation follows.
- 1
Specify
Define the goal, the journey, and the non-goals
- 2
Review
Check the spec for gaps and contradictions
- 3
Plan
Break it into discrete, sequenced tasks
- 4
Implement
Agents build against the spec
- 5
Verify
Test the result against the criteria
- 6
Replan
Requirements changed? Update the spec first
BrainGrid runs this cycle for you as The BrainGrid Loop: describe an idea, answer clarifying questions, approve the spec, and load the tasks into your coding agent over MCP.
Three ways to do SDD
Honest map of the tools. They solve different layers of the same problem.
GitHub Spec Kit
Open-source toolkit that scaffolds spec files in your repo.
Pick it when: You are an engineer who wants templates and full manual control inside your editor.
Kiro
An agentic IDE with spec features built into the editor.
Pick it when: You want specs, but you are willing to switch your whole development environment to get them.
BrainGrid
The AI Product Planner. Interrogates your idea, writes the spec with acceptance criteria, scopes tasks, and loads any agent over MCP.
Pick it when: You want the spec written for you, and you want to keep the coding agent you already use.
Spec-driven development, answered
What builders ask before they make the switch.
Spec-driven development is a methodology where you write a structured specification before writing code, and the spec serves as the source of truth for what gets built. With AI coding agents, you act as the architect: the spec defines goals, scope, edge cases, and acceptance criteria, and agents generate and validate code against it. It is the disciplined alternative to one-shot prompting.
