You ask an AI agent to build a password reset feature. It ships fast, and it works. Then you look closer: the reset links never expire, the old password gets emailed in plaintext, and there's a new database table nobody asked for.
The agent didn't fail. Your instructions had gaps, and it filled them with guesses.
That's the problem spec-driven development (SDD) is meant to solve. Instead of prompting, checking, and re-prompting until something looks right, you agree on a short spec first: what the feature should do, how you'll know it works, and what's still undecided. Tools like GitHub Spec Kit and Kiro build a workflow around this, but plain Markdown files in your repo do the job too.
The catch
SDD has its own failure modes, and most teams hit them within the first few weeks:
- Waterfall creep. The spec grows until you're designing everything up front and getting feedback too late.
- Spec drift. The code moves on, the spec doesn't, and soon nobody trusts it.
- AI-padded specs. Three pages of confident text with nothing you could write a test against.
- The agent ignores the spec anyway. Long documents get skimmed, and the one rule that mattered gets lost.
I've collected 11 of these problems, each with a practical fix, in a new post on NoloWiz.
What's in the full article
- A one-page example spec for the password reset feature you can copy
- All 11 problems, with a fix for each
- Best practices for writing specs, working with agents, and keeping specs alive
- How to right-size the process, so a typo fix doesn't need the same ceremony as a payments change
- A short FAQ, including the one everyone asks: "Isn't this just waterfall?"
The short version: SDD works when specs are short, testable, and updated along with the code. The details are what make that stick.
๐ Read the full post: Spec-Driven Development: Problems and Best Practices
What's the worst gap an AI agent has filled in for you? I'd like to hear it in the comments.
Top comments (0)