"Build me a login page"
Five developers. Five valid interpretations:
| Developer | What they build |
|---|---|
| A | Email + password form |
| B | "Sign in with Google" button, nothing else |
| C | Magic link sent to email, no password at all |
| D | Username + password + CAPTCHA + "remember me" |
| E | Phone number + SMS code |
Nobody is wrong. The instruction had five unknowns and zero constraints.
Add constraint: "Users log in with email and password"
B, C, E are eliminated. Two remain. Still ambiguous: does it need password reset? Rate limiting? "Remember me"?
Add constraint: "Include password reset. No social login. No CAPTCHA."
Now there's essentially one solution. The spec didn't get more creative. It eliminated degrees of freedom until only one valid answer remained.
This is the solution space.
The set of all valid implementations that satisfy your description. Vague description = huge space. Precise description = tiny space. That's it.
"Store the user's preference"
Even a simple requirement hides decisions:
| Approach | Tradeoff |
|---|---|
| Save on device only | Fast, but lost when they switch devices |
| Save to server | Syncs everywhere, but needs authentication |
| Save in browser cookie | Survives restarts, but has size limits |
| Save to a file | Works offline, but which file? Where? |
Add "must sync across devices" and three options vanish. Add "in real time, without refreshing" and the remaining options narrow to one class of technology. Each constraint does the same thing: kills valid alternatives until what's left is what you actually wanted.
Why AI makes this worse
A human developer would ask: "Did you want social login?" An AI picks one and keeps going. It's not being stupid. It's doing math.
A system with fewer equations than unknowns has infinite solutions.
A spec with fewer constraints than decisions has multiple valid implementations. The AI picks one. You expected a different one. Now you're debugging a misunderstanding, not a bug.
This scales. A login page has maybe 5 decisions. A full application has hundreds. Every unspecified decision is a coin flip that compounds.
The takeaway
Vague spec = wide solution space = surprising outputs.
Precise spec = narrow solution space = predictable outputs.
Spec-driven development works not because it makes AI smarter, but because it eliminates the decisions you didn't want the AI making for you. Be intentional about what you nail down and what you leave open.
Related
- Spec-Driven Development — The spec is the product
- Vibe Coding vs Spec-Driven — When each approach fits
- Matrix Methodology — How to write specs that constrain effectively