Agents move faster than review.
A vague prompt can produce a large diff before anyone notices the architecture is wrong.
Learn
What is spec-driven development?
Spec-driven development means defining the behavior, constraints, architecture, and acceptance criteria before implementation begins. With AI coding agents, it becomes even more important: agents can write code quickly, so the design they build from must be explicit, reviewable, and kept in sync with the code.
Spec-driven development starts with intent, not implementation.
In spec-driven development, the team writes down what should be true before writing the code: user behavior, system constraints, interfaces, acceptance criteria, edge cases, and important design decisions. The spec becomes the yardstick for implementation and review.
The point is not to create more paperwork. The point is to make the design clear enough that humans and coding agents can build the same thing.
The reframe
Prompt-driven development asks the agent to infer the design. Spec-driven development gives the agent the design.
A prompt can describe a task, but it often leaves important intent implicit. The agent has to infer constraints, architecture, edge cases, and success criteria from whatever context happens to be loaded. A spec makes that intent explicit before the agent starts editing code.
| Workflow | What the agent gets | Main risk |
|---|---|---|
| Prompt-driven | A task description and partial context | The agent fills gaps with guesses |
| Ticket-driven | A work item and maybe acceptance notes | The design may be scattered elsewhere |
| Spec-driven | Explicit behavior, constraints, architecture, and acceptance criteria | Requires discipline to keep the spec current |
Prompting harder is not the same as specifying better.
AI coding
When implementation gets faster, unclear intent gets more expensive.
AI coding agents reduce the cost of producing code. That changes the bottleneck. The hard part is no longer typing every line by hand; it is making sure the generated code matches the system the team actually wants to own.
Implicit constraints get missed.
The agent may not know the security, data, or product rule that was obvious to the developer.
Local fixes create system drift.
The agent solves one issue while bending the design somewhere else.
Large changes need sequencing.
Refactors, migrations, and rollouts need ordered steps, not one giant instruction.
Future agents need the reason.
The next run should inherit the decision, not rediscover it from code diffs.
Specs are how teams preserve intent when code becomes cheap to generate.
Anatomy
A useful spec explains what, why, and how to know it worked.
A spec does not need to be long. It needs to be precise. The best specs give a coding agent enough context to implement safely and give a human enough structure to review the result.
- Goal — what outcome the change should create.
- Background — why the change matters and what already exists.
- Scope — what is included.
- Non-goals — what should not be changed.
- User behavior — what users or systems should observe.
- Architecture notes — components, boundaries, data flow, dependencies, and constraints.
- Contracts and schemas — APIs, events, database models, payload shapes, and interface expectations.
- Edge cases — failure modes, lifecycle states, permissions, limits, and unusual flows.
- Acceptance criteria — specific checks that define done.
- Review notes — risks, rollout concerns, migration steps, and open questions.
A good spec reduces the number of things the agent has to invent.
Planning
Big specs need ordered work.
A spec explains what should be true. A plan explains how to get there safely. For small changes, a spec may be enough. For cross-cutting work, the spec should be decomposed into tasks with objectives, dependencies, acceptance criteria, and prompts the coding agent can execute one step at a time.
- Start with the spec. Capture the behavior, architecture, constraints, and success criteria.
- Identify boundaries. Note which modules, services, data models, and interfaces are affected.
- Break work into tasks. Keep each task small enough to review.
- Attach acceptance criteria. Make done visible before the agent starts.
- Run and record progress. Track what happened so the next task starts from the current truth.
Spec-driven development does not stop at writing the spec. The spec should drive the plan.
Architecture
Coding agents need technical intent, not only product intent.
A spec that only describes user behavior may still leave the agent guessing about architecture. For AI-assisted development, a useful spec should include the technical constraints that keep the system coherent.
- What components or services should own this behavior?
- What APIs, events, or schemas must remain stable?
- What data model changes are allowed?
- What migration or rollout path is required?
- What security, privacy, or access rules must be respected?
- What existing patterns should the agent follow?
If architecture is not in the spec or project memory, the agent will infer it from partial code context.
Drift
A stale spec is just another kind of missing context.
Specs are valuable only if they remain close to the code. When the implementation changes but the spec does not, the next developer or agent starts from old truth. Spec-driven development needs a writeback loop: after implementation, update the source of truth to reflect what changed.
- Review against the spec. Check whether the implementation matches the behavior, constraints, and acceptance criteria.
- Record deviations. If the implementation changed the design, make that explicit.
- Update decisions. Capture important tradeoffs and rejected alternatives.
- Keep future agents grounded. The next agent should read the current system design, not yesterday's plan.
The spec is not a document you finish before coding. It is the source of truth you maintain as the system evolves.
Windy
Windy makes spec-driven development agent-native.
Windy gives developers and coding agents one shared source of truth for specs, diagrams, architecture, plans, tasks, and execution history. Humans review and shape that source of truth in the web app. Coding agents read and write it over project-scoped MCP.
Windy Docs — the spec and design memory.
Specs, requirements, architecture notes, diagrams, contracts, schemas, and decisions.
Windy Plans — the execution layer.
Ordered tasks, objectives, dependencies, acceptance criteria, prompts, and execution logs.
Your coding agent still writes the code. Windy gives it the spec, plan, and project memory it should build from.
What spec-driven development looks like with a coding agent.
Scenario: A team wants to add team invitations to a SaaS app.
Without a spec
The developer asks an agent to “add team invites.” The agent creates a flow, but may guess invitation states, permissions, email behavior, expiration rules, audit logging, and how invited users attach to an organization.
With a spec
- The spec defines invitation states: pending, accepted, expired, revoked.
- It explains who can invite users and which roles can be assigned.
- It defines the email and token expiration behavior.
- It names the API contract and database changes.
- It lists acceptance criteria for invite creation, acceptance, expiration, revocation, and duplicate handling.
- The plan breaks the change into backend, UI, email, tests, and migration tasks.
- The coding agent reads the spec and task before editing code.
- After implementation, the spec and execution notes are updated.
The agent is not being asked to invent the product. It is being asked to implement a design.
Pitfalls
Common mistakes in spec-driven development.
Writing vague specs.
A spec that says “make billing better” is just a long prompt with a title.
Skipping non-goals.
Agents need to know what not to change.
Leaving architecture out.
Product behavior without technical constraints still leaves room for architectural guessing.
Writing specs once and abandoning them.
A stale spec can mislead future agents.
Making specs too heavy.
The spec should be precise enough to guide work, not so bureaucratic that nobody updates it.
Not tying specs to acceptance criteria.
Without done checks, review becomes subjective.
FAQ
Questions, answered.
Spec-driven development is a workflow where behavior, constraints, architecture, and acceptance criteria are defined before implementation, then used to guide and review the code.
No. TDD starts with tests. Spec-driven development starts with the broader intent: behavior, architecture, constraints, and success criteria. Tests may come from the spec.
No. Specs can be small, iterative, and updated as the system changes. The point is explicit intent, not big upfront bureaucracy.
Agents can generate code quickly, but they need explicit context. Specs reduce guessing by giving the agent the design, constraints, and acceptance criteria before it edits code.
Long enough to remove dangerous ambiguity. Small changes may need a short spec. Cross-cutting work may need architecture, diagrams, contracts, and an execution plan.
Windy stores specs, diagrams, architecture notes, and plans in one project memory, then exposes that memory to coding agents over MCP so they can build from the design and update it as behavior changes.
Related
Keep exploring.
Give your coding agent the spec before it writes the code.
Your coding agent still writes the code. Windy gives it the spec, plan, and project memory it should build from.
windylogic.ai