Spec-driven development,
ship with clarity.
Spec Coding shifts decisions from code review to pre-coding design: define acceptance criteria, edge cases, and counter-examples before implementation begins — so product, engineering, and QA agree on "done" before a single line ships.
Start with the thing you need today
Pick the shortest path from vague requirement to reviewable spec. No signup, no workflow ceremony.
Use a proven template
Start with feature, API, or database spec structure and adapt it inside your repo.
Turn notes into a spec
Fill a focused form and get Markdown with goals, non-goals, acceptance criteria, and edge cases.
Check before implementation
Use the review checklist to catch missing scope, dependencies, rollout notes, and test evidence.
Spec-first development path
Start with the method, then move into scope, acceptance criteria, review gates, and release evidence.
API contract path
Use this path for schema diffs, compatibility, error taxonomy, versioning, webhooks, and deprecation plans.
Acceptance criteria path
Turn vague success statements into Given/When/Then criteria with failure paths and release evidence.
AI coding governance path
Connect prompts, risk registers, acceptance criteria, and test evidence before generated code reaches production.
Why write the spec first?
Most rework isn't caused by bad code — it's caused by misaligned assumptions. A spec makes hidden decisions visible before implementation, so everyone means the same thing when they say "done."
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.
How teams turn specs into daily practice
Spec Coding works best when a short artifact becomes part of the delivery loop, not a document that sits beside the work.
Use the spec to find the first real decision
Start with the smallest unresolved decision: scope, permissions, error behavior, data migration, rollout, or rollback. A useful spec names that decision and makes the owner visible before estimates begin.
Ask reviewers for evidence, not opinions
Product can check non-goals, engineering can check dependencies, QA can map acceptance criteria to tests, and support or operations can check failure paths. The review is successful when every risk has a next action.
Keep the final spec near the code
Link the finished artifact from the issue, pull request, release note, or runbook. Future changes become easier when the team can see the reason behind an API field, edge case, or rollout decision.
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?
The most expensive specs are the ones you skip. A short spec that catches one scope ambiguity before code review saves a week of rework. Start with the decisions that have historically caused you the most production pain: acceptance criteria, edge cases, and rollback plans.
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.
What if requirements change mid-sprint?
Update the spec. That's the point — specs are living documents, not contracts carved in stone. Version them in git alongside your code. The spec always reflects current truth.
How is a spec different from a PRD?
A PRD describes what the product should do from a business perspective. A spec describes what the code must do from an engineering perspective — with acceptance criteria, edge cases, and testable contracts. They complement each other.
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.
AI Coding Spec Packet
A copy-ready packet for giving AI coding tools a bounded task, acceptance criteria, file ownership, tests, and review evidence before generation starts.
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.
Spec Generator
Fill a form, get a complete feature spec in Markdown — with acceptance criteria, edge cases, and non-goals. Free, no signup.