Scope drift
The assistant adds adjacent refactors, new fields, or product behavior that nobody reviewed.
Write spec.md before
the agent codes.
Spec Coding turns a vague AI coding request into a short, reviewable packet: context, scope, acceptance criteria, allowed changes, and evidence before the first generated diff.
The problem is not that AI writes code. It is that it guesses the missing spec.
Most failed AI-assisted changes start with a prompt that hides scope, edge cases, ownership, and proof. Spec Coding makes those decisions visible before the agent edits files.
Untestable acceptance
The PR looks plausible, but reviewers cannot map the diff to clear user-visible behavior.
Missing evidence
Tests, screenshots, logs, rollout signals, and rollback paths are invented after the code lands.
Weak handoff
“Build coupon codes for checkout. Make invalid codes work nicely.”
Spec handoff
- Context: checkout route, totals module, coupon table
- Scope: one valid coupon before payment intent creation
- Non-goals: admin UI, stacking, totals refactor
- Evidence: validation tests, checkout integration test, rollback flag
How it sits next to neighboring methods
Spec Coding is not a full product process and not a heavy formal spec system. It is the small working file between a vague chat prompt and a production diff.
| Method | Primary artifact | Best for |
|---|---|---|
| Vibe coding | chat only | Exploration, throwaway scripts, and prototypes where being wrong is cheap. |
| spec-coding | feature.spec.md | Day-to-day feature work where alignment matters but a 30-page PRD is too much. |
| SDD / formal spec | spec.md + design.md + tasks.md | Regulated systems, multi-team delivery, and changes where wrong code is expensive. |
| Working Backwards | PR / FAQ | Product framing before implementation. Spec Coding handles one feature below it. |
| Shape Up | pitch + appetite | Cycle planning and shaping. The spec is the implementation agreement inside the shaped work. |
Terminology note
People search for this practice as spec-first, spec as code, code spec, spec code, or coding spec. On this site, all of those point to the same practical artifact: a short spec.md kept close to the code and reviewed before implementation.
One change, one reviewable packet
A single spec.md is enough for small work. Riskier changes need a tiny folder that separates intent, behavior, design, tasks, and evidence so reviewers can challenge the right layer.
docs/specs/checkout-coupon/
proposal.md why this change matters, who is affected spec.md requirements, scenarios, non-goals design.md decisions, trade-offs, rollout path tasks.md implementation slices and allowed scope test-evidence.md proof required before merge
AI coding workflow
Use this path when the next step is a real change in a real repo. Each item points to a page, template, example, or generator you can use immediately.
01
Name the risk
Understand why vague AI prompts create scope drift, hidden edge cases, and weak review evidence.
02
Anatomy of a spec
Context, goal, plan, out of scope, acceptance, and evidence.
03
Pick the smallest template
Choose the file that matches the change: feature, API, database, design, tasks, or evidence.
04
Study a worked example
See how a loose request becomes a reviewable implementation contract.
05
Review before implementation
Use twelve questions before handing the work to a human developer or AI coding agent.
06
Generate the handoff packet
Produce spec, tasks, acceptance criteria, and evidence checklist from a requirement.
07
Go deeper into SDD
Move from one spec file to spec.md, design.md, tasks.md, and evidence.md.
AI Coding Spec Packet
Copy the starter spec, or generate the full packet with spec.md, tasks.md, acceptance criteria, and evidence checklist.
Six resource paths
Pick the path that matches your current job. The site is organized around reusable artifacts, not passive reading.
Start here
Learn the lightweight habit: write the decisions that stop rework before code starts.
Templates
Copy repo-ready Markdown files for features, APIs, database changes, tasks, and evidence.
Examples
Compare vague requests with finished spec packets for checkout, APIs, migrations, and notifications.
Generators
Generate spec packets, Gherkin scenarios, API specs, database specs, and postmortem notes.
Review gates
Use checklists and evidence requirements to decide whether a change is ready for implementation.
AI handoff
Give Claude Code, Cursor, Codex, or another agent a narrow source of truth before it writes code.
Anatomy of a spec
The useful version is small enough to write before momentum disappears, but specific enough to stop an agent from wandering.
Context
Where this lives, which files already matter, and which existing patterns should be reused.
Goal
The user or system behavior that changes after the work ships.
Plan
Reviewable implementation steps, named files, dependencies, and test commands.
Out of scope
The adjacent refactors, nice-to-haves, and tempting side quests the agent must not start.
Acceptance and evidence
Observable criteria plus the tests, logs, screenshots, or rollout signals needed before merge.
review-ready-spec.md
spec.md
## Context Existing checkout totals are computed in billing/totals.ts. ## Goal Apply one valid coupon before payment is created. ## Plan 1. Validate coupon through a small API endpoint. 2. Update checkout summary after validation. 3. Keep draft order state idempotent. ## Out of scope - coupon admin UI - multi-coupon stacking - unrelated totals refactor ## Acceptance - expired coupons show inline error - payment amount uses discounted total - refresh keeps the selected coupon ## Evidence - unit test for validation rules - integration test for checkout total - rollback flag documented
Template library
Templates are presented like repo files because that is how teams actually use them: open, copy, edit, review.
| File | When to use | Lines | Updated | Action |
|---|---|---|---|---|
feature.spec.md |
Standard feature work: new endpoint, new screen, or new flow. | 42 | 2026-05-15 | open |
api.spec.md |
API contracts, request/response examples, errors, and compatibility rules. | 48 | 2026-05-15 | open |
database.spec.md |
Schema changes, indexes, constraints, backfills, and rollback planning. | 39 | 2026-05-15 | open |
spec.md |
Goal, non-goals, acceptance criteria, open questions, and evidence required. | 36 | 2026-05-11 | open |
design.md |
Architecture choice, interfaces, rejected alternatives, rollout, and rollback. | 52 | 2026-05-11 | open |
tasks.md |
Reviewable implementation slices with allowed files and test commands. | 44 | 2026-05-11 | open |
evidence.md |
Tests, screenshots, logs, metrics, manual checks, and release stop signals. | 31 | 2026-05-11 | open |
Copy area
template.md
Click any “Copy template” button above to preview the content here.
From vague request to reviewable spec
The method is easiest to trust when you can see the before and after. This example turns a loose product request into scope, plan, acceptance, and evidence.
Before
“Add coupon codes to checkout. Make sure invalid codes do not break payment.”
After
- Context names checkout, billing totals, and existing coupon data.
- Goal limits the behavior to one coupon before payment.
- Out of scope blocks coupon admin, stacking, and totals refactors.
- Acceptance covers expired, reused, and valid coupon states.
- Evidence names unit tests, integration test, and rollback flag.
after.spec.md
## Acceptance - expired code shows inline error - already-used code cannot be applied twice - payment amount uses the discounted total ## Evidence - coupon validation unit test - checkout total integration test - rollback flag documented
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.
Is spec coding the same as spec-first, spec as code, or code specs?
They overlap. Spec-first describes the habit of writing behavior before code. Spec as code keeps that spec in the repository. Code spec, spec code, and coding spec are common search phrases for the same small artifact: a reviewable spec.md that guides implementation.
Featured operating guides
Start with the pieces that make AI-assisted delivery more controllable: first principles, handoff packets, and pre-code review gates.
Foundations
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
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.
Review
Spec Review Checklist Before Coding
Twelve practical checks for scope, non-goals, acceptance criteria, edge cases, allowed files, test evidence, and rollout signals before implementation starts.
Ready to hand AI a better spec?
Generate a packet, copy it into your issue or pull request, then let the agent code against clear scope, acceptance criteria, and evidence.