Spec-driven development,
ship with clarity.
Spec Coding is a lightweight but powerful approach: define acceptance criteria, edge cases, and counter-examples before coding — aligning product, tests, and implementation, and making AI-assisted coding reliable and controlled.
Why write the spec first?
You don't lack code — you lack shared truth. A spec turns fuzzy requirements into verifiable facts, improves collaboration, and keeps AI outputs from drifting.
Capture edge cases upfront
Stop guessing. Define what must succeed or fail — and reduce rework dramatically.
Acceptance = test cases
Use Given/When/Then or checklists to make delivery executable and reviewable.
Make AI code to the spec
A spec is stable context. Not chat — versioned source-of-truth.
A 3-step Spec Coding workflow
Lightweight, no ceremony. Repeatable, reviewable, reusable.
Define: goal / non-goals / acceptance
- One-line goal + counter-examples (what NOT to do)
- Acceptance criteria (testable & reproducible)
- Edge cases (nulls, duplicates, concurrency, permissions)
Spec → tasks → test checklist
- Split into modules and interfaces
- Write tests/assertions before implementation
- Change one module at a time to avoid scope drift
Let AI code to the spec — not to vibes
Treat the spec as the single source of truth. AI must stay within constraints: no surprise features, no field changes, no wandering. That's reliable AI-assisted development.
Copy-paste templates
Standardize how you write clarity — then evolve your team conventions over time.
Feature spec template
Goal / non-goals / acceptance / edge cases / output in one page.
API spec template
OpenAPI structure + error conventions + request/response examples.
DB spec template
Fields, constraints, indexes, migration plan, compatibility notes.
Click any “Copy template” button above to preview the content here.
FAQ
A few things you may be wondering.
Won't specs slow us down?
Spec Coding focuses on the minimum viable spec. Write the 20% that causes 80% of rework: acceptance, edges, counter-examples. 10 minutes of spec saves hours of rework.
If I already use AI to code, do I still need specs?
Even more. Without specs, AI drifts: extra features, changed fields, non-stop rewrites. Specs are guardrails.
Is it good for solo builders and small teams?
Yes — small teams suffer most from lost context and verbal agreements. Specs make you productive even after context breaks.
From the blog
Practical long-form guides on spec-first delivery — from writing your first spec to adopting the practice across a team.
What Is Spec-First Development?
The complete introduction to spec-first: what it means, how it differs from standard agile delivery, and the three questions every spec must answer before coding starts.
How to Adopt Spec-First in a Team
A 30-day adoption roadmap with weekly checkpoints, from individual pilot to team-wide practice. Includes how to measure whether it's working.
Harness Engineering vs Spec-First
Both practices catch bugs early — at different layers. Spec-first defines correctness before coding. Harness engineering verifies it automatically on every commit.
Free resources
Downloadable templates, checklists, and prompt packs — ready to drop into your repo.
Spec Templates
Feature, API, and database spec templates in Markdown. Copy them into /docs/specs/ and start writing.
Checklists & Guides
Spec review checklists, API contract checklists, edge case identification guides, and PRD-to-spec conversion workflows.
30+ Downloads
Prompt packs, decision matrices, risk models, governance policies, and runbooks — all free, all Markdown.