Scope drift
The assistant adds adjacent refactors, new fields, or product behavior that nobody reviewed.
Fixed by## Out of scope
Spec-first for AI coding agents
See the coupon case
Write
Write spec.md before
the agent codes.
Spec Coding turns a vague AI coding request into a short, reviewable packet before the agent writes its first diff. The coupon case shows what thirty minutes of writing catches up front: an unbounded scope, an untestable “make it work nicely”, and no rollback path.
−"Build coupon codes for checkout. Make it work nicely."
+AC-1: an expired code shows an inline error, total unchanged
+AC-2: a code already used on another order cannot be applied twice
+AC-3: the payment intent amount equals the discounted total
The problem
AI doesn't fail at writing code. It fails at guessing the missing spec.
Most rework isn't code quality—it's misaligned assumptions. If you can write the spec in ten minutes, you usually save the agent from three wrong passes. If you cannot, the feature probably is not ready to build.
Untestable acceptance
The PR looks plausible, but reviewers cannot map the diff to clear user-visible behavior.
Fixed by## Acceptance
Missing evidence
Tests, screenshots, logs, rollout signals, and rollback paths are invented after the code lands.
Fixed by## Evidence
One change, one packet
Anatomy of a reviewable spec
A single spec.md is enough for small work. Riskier changes get a tiny folder that separates behavior, tasks, and evidence, so reviewers can challenge the right layer. Here is the same coupon change, file by file.
- 01
Context
Where this lives, which files already matter, and which existing patterns should be reused.
- 02
Goal
The user or system behavior that changes after the work ships.
- 03
Plan
Reviewable implementation steps, named files, dependencies, and test commands.
- 04
Out of scope
The adjacent refactors, nice-to-haves, and tempting side quests the agent must not start.
- 05
Acceptance and evidence
Observable criteria plus the tests, logs, screenshots, or rollout signals needed before merge.
## 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
## T1 Validate endpoint Files: apps/api/routes/coupons.ts, apps/api/routes/coupons.test.ts Done when: expired, used, and unknown codes return typed errors Run: pnpm test coupons ## T2 Checkout summary input Files: apps/web/routes/checkout/CouponInput.tsx, CheckoutSummary.tsx Done when: inline error renders, total is unchanged on failure ## T3 Totals + draft order Files: packages/billing/totals.ts, packages/orders/draft.ts Done when: payment intent amount equals the discounted total ## Not allowed - editing computeTotals internals beyond the discount input - new coupon admin routes
## Before merge - [ ] unit: validateCoupon rejects expired + already-used codes - [ ] integration: checkout total with coupon == payment intent amount - [ ] screenshot: inline error state on the summary card - [ ] refresh keeps the applied coupon on the draft order ## Rollout - flag: checkout_coupon_input (default off) - watch: payment_intent_amount_mismatch == 0 for 24h - rollback: turn the flag off; no data migration to revert
Positioning
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. 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.
Workflow
AI coding workflow
Use this path when the next step is a real change in a real repo. Each step points to a page, template, example, or generator you can use immediately.
01
Name the risk
Why vague AI prompts create scope drift, hidden edge cases, and weak review evidence.
02
Pick the smallest template
Choose the file that matches the change: feature, API, database, design, tasks, or evidence.
03
Study a worked example
See how a loose request becomes a reviewable implementation contract.
04
Review before implementation
Twelve questions to ask before handing the work to a developer or an AI coding agent.
05
Generate the handoff packet
Produce spec, tasks, acceptance criteria, and an evidence checklist from one requirement.
06
Go deeper into SDD
Move from one spec file to spec.md, design.md, tasks.md, and evidence.md.
Template library
Open, copy, edit, review.
Templates are presented like repo files because that is how teams actually use them. Copy puts the Markdown on your clipboard and previews it below.
| 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 |
FAQ
Questions teams ask first
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.
Next change
Write the spec before the next prompt.
Paste one requirement, get spec.md, tasks.md, acceptance criteria, and an evidence checklist. Generated locally in your browser.