Most of how I build things now starts with a document, not a file of code. I’ve ended up working in a style people call spec-driven development, and it has changed both how fast I build and how much I actually understand what I’ve built. This post is about what it is, why it works, and how I use it day to day.
What It Actually Means#
The simple version: you write a detailed specification of what you want before any code exists, and the spec — not the prompt, not the code — is where the real decisions live. A coding agent then translates that spec into working software.
The contrast is with what I’d call prompt-and-pray: you type “build me an app that does X,” accept whatever comes out, and then spend the rest of the day fixing it. That can work for something tiny, but it falls apart the moment the project has structure — a data model, multiple files, features that depend on each other. Those projects don’t need a better prompt. They need a plan.
So the mental shift is this: the spec is the design. It decides the data model, the tech stack, the file structure, the build order, the constraints. The agent’s job is the translation into syntax, which is now the cheap part. The expensive part — the thinking — is the document.
The Loop I Use#
In practice it’s a loop, not a single step. With Claude Code it looks like this:
- Brainstorm to a concept. Before writing the spec, I figure out roughly what I’m building and why. Sometimes that’s a conversation with the AI, sometimes with a person.
- Write a detailed spec. I get the agent to produce a first
PLAN.md— data model, features, phases, and the constraints that matter (what must not break, what’s out of scope). - Read it critically and push back. This is the most important step. The first plan is a draft, not an answer. I’ve changed tech stacks, restructured data models, and reordered the build at this stage — before a single file is created and a single mistake is expensive.
- Iterate. I’ll often run the plan back through a separate conversation to refine it further, two or three rounds, until the decisions are all explicit and I agree with them.
- Execute. Only then does the agent build it. Because the plan is precise, the output is usually clean on the first run.
- Review and finish. I read the result and handle the things a spec can’t decide — usually the UI and the feel of an interaction.
I also keep a small prompting habit for step 2 so the spec comes out structured and complete rather than as a wall of vague intentions. Garbage spec in, garbage code out.
Why It Works#
The thing that surprised me at first was how often a well-specified project just runs the first time — no debugging session, no broken dependencies. I used to read that as luck. It isn’t.
A vague prompt produces broken code; a precise spec produces working code. “First try” is a symptom of a good plan, not an accident. Which means the way to get better output isn’t to get better at prompting tricks — it’s to get better at thinking through the design before you ask for anything. The leverage moved from typing to deciding.
What Stays Human#
Spec-driven development doesn’t remove me from the project; it moves me to the parts that actually need judgment.
- The decisions are mine. Tech stack, data model, what’s in scope — the agent can propose, but I’m the one who approves or rejects, and I have to be able to defend why.
- Taste is mine. An agent can’t tell whether a layout feels right. Anything visual, I check and adjust myself.
- Understanding is mine. This is the part it would be easy to skip and shouldn’t be. If I can’t read the result and explain it, I haven’t really built it — I’ve just commissioned it. Because the spec describes every mechanism in words, reading the code afterwards is mostly a matter of matching it back to the plan I already wrote.
Where It Breaks Down#
It’s not magic. It struggles when the goal is vague — “make this better” produces nothing useful, because there’s nothing concrete to translate. It struggles with work that’s about feel rather than logic. And it quietly fails if you let yourself stop understanding the output; a plan you didn’t internalize is just someone else’s code in your repository.
What I Learned#
The biggest takeaway is a skill that has nothing to do with AI: spec-driven development has made me much better at breaking work into clear, concrete pieces and being precise about what I actually want. That’s useful whether you’re briefing an agent or a teammate. The agent just punishes vagueness faster, which turns out to be a good teacher.