Scope drift
The assistant adds adjacent refactors, new fields, or product behavior that nobody reviewed.
Fixed by## Out of scope
spec.md beforeSpec coding means turning a vague AI coding request into a short, reviewable spec before the agent writes its first diff. In 78 recorded Claude Code runs, 28 of 30 runs with a spec passed every hidden check; 12 of 48 runs without one did.
Most rework isn't code quality—it's misaligned assumptions. A one-line prompt leaves every unstated decision to the model, and the model will make one. If you cannot write the spec, the feature probably is not ready to build.
The assistant adds adjacent refactors, new fields, or product behavior that nobody reviewed.
Fixed by## Out of scope
The PR looks plausible, but reviewers cannot map the diff to clear user-visible behavior.
Fixed by## Acceptance
Tests, screenshots, logs, rollout signals, and rollback paths are invented after the code lands.
Fixed by## Evidence
Claude Code got three ordinary tickets: a coupon feature, an API error cleanup and a schema change. We ran them 78 times across four Claude models and scored every run with hidden tests frozen before the first one. One-line prompts usually produced code that ran. The spec decided whether it was the code that was asked for.
Across Opus 5.5, Sonnet 5.5, Haiku 4.5 and Fable 5.1, the smallest and largest models landed within two runs of each other.
Compare the four modelsFailures were rarely crashes. They were decisions nobody approved: a dropped column that billing still read, an error shape the mobile app depended on, a coupon with no reuse limit.
Open every prompt, diff and scoreOne vague coupon ticket came back with two reuse policies and two ways of charging a coupon that expires during checkout. The three spec runs matched each other.
Vibe coding vs spec codingA 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.
Where this lives, which files already matter, and which existing patterns should be reused.
The user or system behavior that changes after the work ships.
Reviewable implementation steps, named files, dependencies, and test commands.
The adjacent refactors, nice-to-haves, and tempting side quests the agent must not start.
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
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.
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.
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 |
Spec coding is writing a short, reviewable spec (goal, scope, out of scope, acceptance criteria, and the evidence you expect) before an AI coding agent changes code, then reviewing the agent's diff against that spec instead of against the chat history. It is the hands-on form of spec-driven development (SDD): the spec lives in the repo as spec.md and stays the source of truth for the change.
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.
Even more. Without specs, AI drifts: extra features, changed fields, non-stop rewrites. Specs are guardrails.
Yes — small teams suffer most from lost context and verbal agreements. Specs make you productive even after context breaks.
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.
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.
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.
Paste one requirement, get spec.md, tasks.md, acceptance criteria, and an evidence checklist. Generated locally in your browser.