Blog

The First Spec: What, Not How

5 min read

Writing With One Hand Tied

With the constitution in place, the next step in Spec-Driven Development is the spec — and it comes with one rule that trips every engineering instinct: describe what the product does and why, and say nothing about how. No Astro, no Tailwind, no component names. Just the visitor, their goals, and what “working” actually means.

It feels like writing with one hand tied behind your back. It’s the most useful constraint in the whole flow.

A Spec Is the WHAT and the WHY — On Purpose

My spec for the first slice (001-site-foundation) is built from user stories with priorities and acceptance criteria, plus edge cases, functional requirements, and measurable success criteria. A flavour:

  • US1 (P1): a first-time visitor lands on the home page and, within seconds, understands who Amín is, what he does, and how to go deeper.
    • Acceptance: given a first-time visitor, when the home page loads, then the name, the role, and a one-line bio are visible in the first screen — on mobile and desktop.

Notice what’s absent: how the hero is built, which CSS does the layout, what renders the metadata. That’s not laziness — it’s the point. The spec captures the outcome the visitor needs; the how is a separate decision, made later in the plan, where it can be chosen on the merits instead of smuggled in early.

Keeping technology out does two quiet, powerful things. It keeps the design space open — the plan gets to pick the best tool, not the one you blurted into the spec in a moment of enthusiasm. And it makes the spec readable as intent — it becomes the thing you check the finished build against, instead of a half-committed implementation sketch.

Why I Sliced One Site Into Many Specs

The tempting move is one giant “build the portfolio” spec. I didn’t. I cut the work into independently shippable slices, each with its own SDD loop:

  • 001 — Site Foundation & Home (this spec)
  • 002 — Blog · 003 — Projects · 004 — Deploy & Analytics

Each slice is a viable increment on its own — a clear, fast home page is valuable even before the blog exists. The payoff shows up everywhere downstream: smaller specs are easier to get right, each loop is short enough to actually finish and demonstrate, and — the part that matters most with an AI producing at speed — the blast radius of any one decision stays small. A mistake in the Blog spec can’t quietly corrupt Projects, because they’re separate loops with separate acceptance criteria.

This is the same lesson the rest of the series keeps circling back to: AI makes producing cheap, so the constraint that protects you is scope you can actually verify. Slicing is how you keep each piece verifiable.

Acceptance Criteria Are “Done,” Defined Before the Code

Here’s the move I value most. Each story carries Given/When/Then acceptance criteria, and the slice ships with measurable success criteria. For 001, there were six: ≥95 on a standard audit for performance, SEO, and accessibility; /sitemap-index.xml and /robots.txt reachable; the page renders correctly with JavaScript disabled; every page exposes a unique title, description, and canonical; name and role visible in the first screen.

That list was written before a single line of code existed. Which means “done” stops being a feeling and becomes a checklist.

And that reframes the scariest question in AI-assisted building — how do I trust code an AI wrote? The answer isn’t “read every line and hope.” It’s: define the test before the agent starts, then check the output against it. The spec is the acceptance test. The build either meets it or it doesn’t. Opinion versus opinion becomes output versus criteria — the same shift the constitution gave me, one level more specific.

Writing the what before the how also surfaces gaps on paper, where they’re free. Edge cases I’d otherwise have discovered mid-implementation — OS dark mode with no flash, a missing OG image falling back to a default, the non-ASCII “Amín” rendering correctly in titles and metadata, everything still working with JS off — all got decided in the spec, not improvised by the agent at 2am.

The Recurring Thread

A spec is another place where I do the deciding so the agent can do the producing against a fixed target. The constitution set the rules; the spec sets the goal and the test. Notice that neither one mentions technology yet — and that’s deliberate. The how gets its own step, on its own merits, next.

Takeaways

  • A spec describes the WHAT and the WHY — user stories and acceptance criteria — with technology deliberately left out. It keeps the design space open and makes the spec readable as intent.
  • Slice one product into independent specs (001, 002, 003…). Each is a viable increment, each loop is short, and the blast radius of a decision stays small — which matters most when an AI is producing fast.
  • Acceptance criteria written before code turn “done” into an objective checklist. That’s how you trust AI-written code: define the test first, then check against it.
  • Writing what-before-how surfaces gaps and edge cases on paper, where they’re free to fix — instead of leaving them for the agent to guess at during implementation.

This blog is built slice by slice with Spec-Driven Development. Read the groundwork in “The Constitution Rules Before Code” and “Before the First Line of Code,” or browse the rest at /blog. Next in the series: the blind spot SDD leaves for anything visual — why you need a wireframe between the spec and the plan.