A coding agent can already write a working app in an afternoon. The problem is no longer producing the code; it is something else: without a specification the agent doesn't write worse code, it writes excellent code for the wrong problem. Every question you didn't answer, it answers with a reasonable default, and you find out weeks later. Spec-Driven Development (SDD) attacks exactly that: write down first what the software must do, resolve in writing whatever is ambiguous, and treat the code as the output of that specification. I applied it to a React Native MVP built with Expo that does one thing—show a list of recent earthquakes anywhere in the world—because it is the kind of request that fits in one line and hides more decisions than it seems.
TL;DR
- SDD separates three artifacts: the specification (what and why), the technical plan (how) and the tasks. The agent implements against them instead of against a loose prompt.
- The real value is not the document: it is that ambiguities get flagged and resolved in writing before the agent chooses for you. Which earthquakes make the list, in what order, and what happens offline are product decisions, not code decisions.
- Acceptance criteria are written as a table of cases, and that same table becomes the test. If the row is not in the table, the behavior is undefined.
What Spec-Driven Development is and how it differs from prompting
A prompt is an instruction that gets consumed and disappears. A specification is a versioned file in the repository, reviewed in a pull request, that outlives the agent's session. That is the whole difference, and it is bigger than it looks.
In the typical flow with an agent, you describe the feature in the chat and the result is a thousand lines of code plus a conversation nobody will reread. The important decisions—the minimum magnitude, how many hours back, what happens offline—were made in some intermediate turn of the chat. When someone asks why the app shows a magnitude 2.6 earthquake but not a 2.4, the answer is nowhere.
SDD splits the work into distinct artifacts, each at its own level of abstraction:
Specification → what must happen and why
│
▼
Technical plan → how it gets built (stack, libraries, structure)
│
▼
Tasks → verifiable units of work
│
▼
Implementation → the code the agent writes against the above
The rule that orders everything is that each level talks about its own level. The specification avoids implementation decisions unless they are a real product constraint: "must work offline" or "data never leaves the device" are requirements even though they have technical consequences; "use TanStack Query" is not. The plan does name technology, but it doesn't reopen product decisions. When that separation holds, you can switch stacks without rewriting the specification, and change a threshold without touching the plan.
There are tools that formalize this flow. GitHub's Spec Kit installs a set of commands in your agent that produce exactly these artifacts in folders of the repository:
# Installs the flow in the project and picks the agent you are going to use.
uvx --from git+https://github.com/github/spec-kit.git specify init quakes-app
# From there, inside the agent:
# /constitution → project principles (apply to every feature)
# /specify → this feature's specification
# /clarify → resolves the ambiguities flagged in the spec
# /plan → the technical plan
# /tasks → the task breakdown
# /implement → executes the tasks
You don't need the tool: three markdown files in specs/ and the discipline to maintain them are enough. What it adds is that the agent has the commands, the templates and the order already loaded, and doesn't skip steps.
Keep reading
That is the first half. The full walkthrough — with the rest of the implementation, the trade-offs and the things that only show up in production — is on my blog:
Read the full post on ramonchancay.me →
Originally published at www.ramonchancay.me/blog/spec-driven-development-react-native-earthquake-app.
Top comments (0)