Starting with Spec-Driven Development: Spec first, Prompt later.

Bringing the ideas I've been thinking about for months into life has never been easier, thanks to AI agents. The basic intuition is—give it a prompt, it builds the whole feature, the result looks good. Done. It takes only minutes to build the same thing that would've taken hours otherwise. Yes, I know, everyone's doing that. Right? The reason I'm opening like this is to point out what happened afterwards. I tried to use the search bar, and it fired a request on every keystroke. Wait, what? I didn't do that. Of course I'd add a debounce here. But the agent didn't. Why? I didn't ask it to. I said—build me a search bar, and it built me one that works; but I didn't say exactly what I wanted. Also, I noticed that the search button changes color on hover, but I'd already told it not to do that. The agent forgot, it hallucinated. What's missing then? What was missing was I did not provide the agent with the exact decisions to work with the feature; or did not provide a proper reference point to fallback to, to remediate the hallucination. In other words, I did not provide it with a proper spec. Hence, it took the hidden decisions itself; even though it pulled the feature off. This is the core problem that Spec-Driven Development (SDD) solves. The Hidden Product Decisions Your AI Agent Is Making For You Here's what happens when you describe something to an AI agent and it generates code: lots of decisions get made. Let's take the search bar implementation as an example. Does the filtering happen on the client or the server? Does the URL update so results are shareable? What does an empty query show? Everything, or nothing? I tend to miss nitty-gritty details while reviewing tons of AI generated code in a short amount of time. The code works, the UI looks right, I move on… Every one of those is a decision that belongs to my product. If I don't make the decisions consciously, the agent takes them based on whatever pattern shows up most often in its training data. Take that se