Spec-First Planning - Vibe Coding, Shipped Right

What You'll Learn

Why a written spec is the antidote to scope creep and context rot
The anatomy of a lightweight, living SPEC.md
How to write user stories with testable acceptance criteria
How to define a small data model and API surface — MVP first
How to slice the work into milestones the assistant builds one at a time
Hands-on lab: write and commit SPEC.md for the snippet vault, with the AI drafting and you deciding

Prerequisites: Module 2 — the snippet-vault repo with its scaffold and context file.

Why Spec-First?

Vibe coding without a plan feels fast — for about twenty minutes. Then the assistant starts guessing what you meant, adds things you didn't ask for, contradicts an earlier choice, and you're firefighting instead of building. A spec is simply the decisions made once, in writing, so neither you nor the AI has to re-guess them.

Without a spec	With a spec
The AI invents scope you never wanted	Scope is fixed and visible — easy to say "not now"
"Done" is a feeling, argued about later	"Done" is acceptance criteria you can check
Context rot: the model forgets earlier decisions	The spec is durable memory the model re-reads
One giant vague prompt, unpredictable result	Small tasks sliced from the plan, one at a time

A spec is a contract, not a novel

It's a short, living SPEC.md in your repo — a page or two. It's the shared contract between you and the assistant. You'll update it as you learn; that's expected. Its job is to make "what are we building?" answerable at a glance.

Anatomy of a Good Spec

Keep it lightweight. Six sections cover almost any small app:

Section	Answers
Problem & goal	What are we solving, and for whom?
User stories	What can a user actually do?
In scope / Non-goals	What we will — and explicitly won't — build now.
Data model	The core things we store and their fields.
API / screens	The endpoints or pages that deliver the stories.
Milestones	The order we'll build it in, smallest useful slice first.

Here's the skeleton you'll fill in during the lab:

# Snippet Vault — SPEC

## Problem & goal
Developers lose useful code snippets. Give them one place to save,
tag, and quickly find snippets.

## User stories
- (filled in below)

## In scope
- Create, list, search, and delete snippets.

## Non-goals (not now)
- Accounts / login, sharing, syntax highlighting, folders.

## Data model
Snippet: id, title, language, code, createdAt

## API
GET /snippets?q=      list + search
POST /snippets        create
DELETE /snippets/:id  delete

## Milestones
1. Create + list   2. Search   3. Delete

From Idea to User Stories

A user story captures one thing a user can do, from their point of view, plus how you'll know it works. The classic shape:

The template

As a [who], I want [what], so that [why].
Then: Acceptance criteria — the checkable conditions for "done".

For the snippet vault:

Story: Save a snippet
  As a developer, I want to save a snippet with a title and language,
  so that I can find it again later.
  Acceptance:
   - A form takes title, language, and code.
   - On submit, the snippet appears in the list.
   - Empty title is rejected with a message.

Story: Search snippets
  As a developer, I want to search by title,
  so that I can find a snippet fast.
  Acceptance:
   - Typing in the search box filters the list live.
   - Search is case-insensitive.
   - No match shows a friendly "nothing found" state.

Why criteria matter here

Those acceptance lines aren't bureaucracy — they become your test cases in Module 6, and they tell the assistant exactly when to stop. "Done" stops being an argument.

Slice Into Milestones

Never hand the assistant the whole spec and say "build it." Slice into thin vertical milestones — each one a small, working, shippable increment. Build the smallest useful thing first (your MVP), then layer on.

# Milestone plan (task list)
[ ] M1  Create + list snippets (title, language, code) end to end
[ ] M2  Search box filters the list by title
[ ] M3  Delete a snippet
[ ] M4  Validation + empty/error states
# Each milestone: one branch, tests, review, commit.

Ruthlessly cut the MVP

The fastest way to finish is to build less. Every "wouldn't it be cool if…" goes under Non-goals, not into M1. You can always promote a non-goal later — but a bloated first milestone is how projects stall.

Let the AI draft, you decide

Great use of the assistant: give it your brief and the skeleton, and ask it to propose user stories, a data model, and a milestone slice. Then you edit — cut scope, fix the model, reorder. The AI is a fast drafter; the product decisions stay yours.

Practical Lab: Write the Spec for Your Snippet Vault

You'll produce a real SPEC.md — AI-drafted, you-decided — with user stories, acceptance criteria, a small data model, and a milestone slice. You'll hand in the committed spec.

What you need

Your snippet-vault repo from Module 2 (scaffold + context file), and your assistant.

1

Write a one-paragraph brief

In your own words: what problem the snippet vault solves and who it's for. Two or three sentences is plenty.

2

Have the AI draft SPEC.md

Paste this, then review what comes back:

Using my brief and CLAUDE.md, draft SPEC.md with these sections:
Problem & goal, User stories (with acceptance criteria), In scope,
Non-goals, Data model, API, Milestones.
Keep the MVP tiny. Propose it — I'll edit. Don't write app code.

3

Make it yours — cut scope

Edit the draft. Move anything non-essential to Non-goals. Keep 3–5 user stories, each with concrete acceptance criteria. Confirm the data model is just Snippet: id, title, language, code, createdAt.

4

Slice the milestones

Order the work smallest-useful-first as a checkbox task list (M1 create+list, M2 search, M3 delete…). This list drives every remaining module.

5

Commit the spec

git add SPEC.md
git commit -m "Add SPEC: stories, data model, milestones"

Then add to REFLECTION.md: which non-goal did you cut to keep M1 tiny, and one place the AI's draft over-scoped that you trimmed? Commit it.

What to hand in

Your snippet-vault repo with SPEC.md. Self-check before submitting:

SPEC.md has all six sections, MVP kept tiny
3–5 user stories, each with checkable acceptance criteria
A milestone task list, smallest useful slice first
New commits for the spec and the reflection

Mini Glossary

Term	Plain meaning
Spec	A short living document of what you're building and why (`SPEC.md`).
User story	One capability from the user's view: as a … I want … so that …
Acceptance criteria	The checkable conditions that make a story "done".
Non-goal	Something you deliberately choose not to build now.
Milestone / slice	A thin, working increment you can build and ship on its own.
MVP	Minimum viable product — the smallest version that's actually useful.

Recap & What's Next

You now have

A committed SPEC.md: the problem, user stories with acceptance criteria, a tiny data model, an API surface, and a milestone slice. The assistant now has a durable contract to build against — and you have a definition of "done".

Next up: Module 4 — Version Control from Line One. Before we build M1, we sharpen the Git habits — branches per milestone, clean commits, and reviewing every AI-generated diff like a pull request.