What is spec-driven development?

Spec-driven development (SDD) means you agree on intent, constraints, and acceptance criteria in writing before (and while) implementation happens—so both people and AI assistants pull in the same direction.

Why SDD matters for AI coding assistants

Large language models are strong at generating code from natural language, but chat sessions are ephemeral. Without durable specs, you get drifting requirements, half-remembered decisions, and “fix it again” loops. SDD moves the agreement into files that live next to your code: proposals, scenarios, design notes, and task lists.

OpenSpec is one way to practice SDD: each feature or change gets a folder under openspec/changes/ with artifacts your assistant can read, update, and archive when done.

SDD vs. “just prompting”

  • Prompt-only: Fast to start, hard to review, easy to lose context when the thread ends or the model forgets earlier constraints.
  • SDD with OpenSpec: Slightly more upfront structure, but reviews are faster (read the proposal and spec delta), onboarding is easier for teammates, and you can resume work days later without re-explaining the feature.

Core ideas

  1. Align before implementation — Capture why and what in proposal.md and specs/ before large code dumps.
  2. Keep artifacts editable — Specs are not frozen contracts; update them when reality changes.
  3. Make progress visible — tasks.md turns work into checkable steps the model can follow systematically.
  4. Archive completed work — Move finished changes to an archive and merge learnings into long-lived specs.

When SDD is worth it

SDD pays off when changes touch multiple modules, involve non-obvious tradeoffs, need review from another engineer, or must hold up under production constraints (security, performance, compliance). For a one-line typo fix, a full change folder may be overkill—use judgment.

Brownfield codebases: OpenSpec is designed so you can adopt SDD incrementally in existing repos without rewriting your stack. See use cases for patterns by team size.

Next steps