Spec-driven development for AI-assisted software delivery
What is Spec-Driven Development?
SDD is the practice of writing a structured, testable specification for every meaningful unit of work before code is touched. The specification defines:
- What success looks like — observable, measurable outcomes.
- What "done" means — explicit acceptance criteria.
- What's out of scope — guardrails against scope creep.
- What the system must guarantee — invariants, edge cases, failure modes.
A good spec is 2-3 pages. It's not a wall of text. It's the contract between business intent and engineering execution.
Why AI needs clear specs
Large language models are excellent at producing code that looks reasonable. They are terrible at knowing what your business needs. Without a spec, the gap between "code that looks right" and "code that does the right thing" becomes invisible until production.
A spec gives the AI a precise target. Same prompt, with vs without a spec:
"Build a payment retry handler"
Without a spec: AI writes a generic retry loop. Misses your refund SLA. No idempotency. No partial-failure handling. Looks fine in review. Breaks in production at 3am.
"Build a payment retry handler perspec-paymt-retry-v3.md"
With a spec: AI implements idempotency, exponential backoff with jitter, partial-failure replay, refund SLA enforcement, and the three custom error codes your team uses. Tests written against the spec. Ships safely.
How SDD reduces rework
Rework costs more than initial development. Studies put the multiplier at 6-100x depending on when the bug is found. SDD reduces rework in three ways:
- Disagreements surface during spec review — when fixing is cheap — not after code is written.
- Ambiguity is eliminated before it propagates into code, tests, and docs.
- Acceptance criteria are unambiguous — engineering and product agree what "done" means before work starts.
In our experience, engagements that start with a written spec materially reduce ambiguity, review cycles, and delivery variance.
How SDD improves predictability
Predictability isn't about velocity — it's about variance. Specs reduce variance because they make scope explicit. When two engineers read the same spec, they should ship the same outcome. When AI agents and humans share the same spec, the same is true.
In engagements that start with a written spec, we consistently see fewer surprises mid-sprint, fewer rework cycles, and clearer go/no-go decisions when unknowns surface during spec review.
SDD + Clean Code + TDD + QA
SDD isn't a replacement for engineering discipline — it's the foundation that makes other disciplines work:
- Clean Code: easier to write when you know exactly what the code must do.
- TDD: tests are derived from the spec, not invented post-hoc.
- QA: testers have a contract to test against. Acceptance criteria become test cases automatically.
- AI orchestration: specs become prompts. Agents have boundaries.
The whole stack moves together. Without specs, every other practice degrades.
Download the SDD Canvas
The same canvas Pernix uses internally to draft every engagement specification. One page. Eight sections. Designed to be filled in by product and engineering together in 60 minutes.
Canvas