The usual way to start a React app is to run a scaffolder (npm create vite) and then start typing. The trouble starts right after. The intent lives in your head or a ticket, the code becomes the only durable artifact, and three weeks later nobody can say what the thing was supposed to do.
Spec-driven development (SDD) flips that. You write the spec first (the intent, the requirements, the acceptance criteria) and treat it as the source of truth. The code is generated from it and kept in sync with it.
The idea isn't new, but coding agents made it practical: a good spec is now something an agent can actually turn into a working scaffold.
Start at spec.md#
Instead of opening a blank App.tsx, you open a spec.md:
# Feature: Saved searches ## Intent Let a signed-in user save a search and re-run it later. ## Requirements - A "Save search" button on the results page, disabled when the query is empty. - Saved searches live under /searches, newest first. - Re-running a saved search restores its exact query + filters. ## Acceptance - Saving an empty query is impossible (button disabled and guarded). - A saved search survives a full page reload. - Deleting one asks for confirmation.
That's the code you review. It's short, it's in plain language, and it's the part that actually decides whether the feature is right.
The loop: specify → plan → tasks → implement#
Tools like GitHub's Spec Kit formalize this into four steps. You specify the intent (above); the agent plans the technical approach (Vite + React Router, a typed SavedSearch model, local persistence); it breaks that into tasks; then it implements: it scaffolds the project, generates the typed components, wires routing, and drafts tests from the acceptance criteria.
You stay in the loop at every gate: you review the plan before any code exists, and you review the code against a spec you already agreed on rather than a blank diff you're seeing for the first time.
That review earns its keep. When I ran this, the plan defaulted to localStorage: fine for a demo, wrong for a signed-in user whose saved searches should follow them across devices.
I caught it at the plan gate instead of a code review three days later. One line added to the spec (searches are per-account, server-persisted), a re-run, and the wrong version never got written.
Why it fits React scaffolding especially well#
Most of the work in standing up a React feature is mechanical: boilerplate, routing, prop types, loading and error states, test setup. That's exactly the work agents do well and humans do tediously. SDD moves your attention to the part machines are bad at: deciding what to build and what "done" means.
The catch, and the senior part: the spec is the new bottleneck. A vague spec generates vague code, confidently. Spec Kit even ships a clarify pass that interrogates a thin spec before it plans, which is a good tell for where the real work is.
SDD forces the hard thinking up front, in language you can review, instead of surfacing it halfway through the implementation. Getting good at it is mostly getting good at knowing what to specify.
Try it#
Spec Kit runs on uv. Three steps take you from nothing to a scaffold you drove from a spec.
1. Install the CLI. This pulls the current build straight from the repo. Append @vX.Y.Z (a tag from its Releases page) to pin a specific version:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git specify --version
Expected: specify is on your PATH and prints its version.
2. Scaffold a project wired for your coding agent:
specify init saved-searches
Expected: a new saved-searches/ directory, and the /speckit.* commands registered for the agent you pick when it prompts.
3. Drive the loop from inside your agent. Paste the spec.md above as the first step:
/speckit.specify # turn the spec into a formal spec doc /speckit.clarify # it asks about anything underspecified /speckit.plan # technical approach — review it before any code /speckit.tasks # a task breakdown /speckit.implement # it builds the scaffold, task by task
These come from whatever specify init registered for your agent, so the exact prefix can vary by agent and Spec Kit version. Check your agent's command list rather than assuming.
Expected: you approve at each gate, first the plan before a line of code exists, then the code against the spec you already signed off on. That's the whole point.
Written by Wilian Revejes, frontend engineer (OTT / Smart TV & video). More at /cv.