Write the spec first — then write the code

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.

Get the Spec Starter See how it works Copy templates

✅ Acceptable ✅ Testable ✅ Collaborative ✅ AI-ready

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.

Less rework

Capture edge cases upfront

Stop guessing. Define what must succeed or fail — and reduce rework dramatically.

Aligned acceptance

Acceptance = test cases

Use Given/When/Then or checklists to make delivery executable and reviewable.

Controlled AI

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.

Step 1

Define: goal / non-goals / acceptance

One-line goal + counter-examples (what NOT to do)
Acceptance criteria (testable & reproducible)
Edge cases (nulls, duplicates, concurrency, permissions)

Step 2

Spec → tasks → test checklist

Split into modules and interfaces
Write tests/assertions before implementation
Change one module at a time to avoid scope drift

Step 3

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

Feature spec template

Goal / non-goals / acceptance / edge cases / output in one page.

API Spec

API spec template

OpenAPI structure + error conventions + request/response examples.

DB Spec

DB spec template

Fields, constraints, indexes, migration plan, compatibility notes.

Copy area

template.md

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.

Start shipping with spec clarity

Get the Starter templates + checklist (drop them into your repo /docs).

Email me the starter Copy templates first