There’s a huge difference between asking AI for something and directing it.
Most devs working with Claude Code, Cursor or whatever agent is in fashion are doing the former: “Build me a login endpoint”, “Create a table component with pagination”, “Add validation to the form”. Prompt by prompt, function by function. And then they wonder why the generated code doesn’t fit, why there’s so much to refactor, why the AI “doesn’t understand the project”.
The problem isn’t the AI. The problem is the flow.
The failure of Prompt Driven Development
When you ask AI for a technical thing directly, you’re asking it to guess the logic. You give it an implementation instruction with no behavioral context. AI is very good at generating code that looks correct. The problem is that it’s optimized to be plausible, not to be faithful to your intent.
The result: code that compiles, tests that pass, and functionality that doesn’t do what you wanted.
Spec Driven Development solves this at the root.
What Spec Driven Development is
SDD is a workflow where you don’t start with functions, endpoints or tables. You start with rules, flows and expected outcomes.
The idea is simple: before the AI writes a single line of code, it has to understand what it needs to build, how it should behave, what it exists for, when to do it and where to put each thing.
It’s the difference between telling a contractor “put a door here” versus handing them the building blueprints and saying “the main entrance has to meet these accessibility, safety and user-flow conditions”. The end result may look similar at first glance, but one has judgment and the other is improvising.
How to build a spec
The basic structure
An SDD specification starts from a user story and expands it with concrete conditions. It’s not technical documentation in the usual sense, it’s a description of the behavior you expect.
A real example of a login spec:
As a user I want to be able to log into the system
to access personalized content
- I log in with email and password
- The user exists in the database
- The user is active
- The form validates email format
- The password must be more than 8 characters
- The form has 2 fields and 2 buttons (submit and clear)
- There is a "Forgot my password" link — not implemented this cycleThen you add the execution paths:
Happy path: the user enters valid credentials, presses submit, the button gets disabled and shows “sending…”, and lands on the home page.
Sad path: invalid credentials, same visual flow, red text appears below the form saying “invalid credentials”, the button re-enables.
This last part is BDD (Behaviour Driven Development) integrated into the spec. It’s not textbook theory — it’s the difference between an AI that generates a generic form and one that generates your form.
The agent flow: letting AI fill in the gaps
The most effective way I’ve found to create specs isn’t writing them from scratch. It’s giving the AI the user story and asking it to make assumptions, then correcting it. The prompt I use:
We're going to define a spec. I'll give you a user story and you'll
have to fill in the blanks. All the things you assumed, non-technical
or functional, you'll show me in a list. Then I'll tell you the
numbers of the assumptions I didn't like and you'll ask me questions
one by one. On each new question you'll show me a progress bar with
the number of questions so far and the ones remaining. You'll also
show me 4 assumption options and a fifth that says "other". When
you're done you'll tell me you're ready to create the specification.The result is an iterative process where you validate the intent and the AI builds the specification. Not the other way around.
When the result convinces you, an Add BDD to the specification closes the loop, and then Create the spec in /specs/login.md persists it in the repository.
Why it works: the repository as the system
There’s a Harness Engineering principle behind all this that deserves its own article: the repository is the system.
AI has no memory between sessions. Its context window degrades past 20-40% capacity. If you work without structure, every session with the agent starts from zero and ends with inconsistent results.
The specs in /specs/ aren’t just documentation. They’re the harness around the model: the persistent context that tells it what exists, how it behaves and what’s already implemented. The model can change (and it will, every few months there’s a better one), but the system —your specs, your rules, your business logic— survives the swap.
It’s like having a company where employees rotate but the processes are written down. You don’t depend on anyone’s tacit knowledge.
What SDD is not
SDD is not writing extensive documentation before coding. It’s not waterfall with extra steps. It’s not a bureaucratic process that slows down development.
It’s precisely the opposite: it’s the way to go faster because the AI executes with less ambiguity. Every correction cycle you save on badly generated code is hours recovered.
There’s also something I think is important to point out: SDD doesn’t remove your technical judgment, it centralizes it. You’re still the one who decides the behavior. The AI implements. That’s exactly the right division of labor with today’s tools.
Who it makes sense for
If you work solo on projects with some business complexity, SDD completely changes the quality of the output you get from any agent. You don’t need to write perfect specs from day one, you need the habit of specifying behavior before asking for code.
If you’re on a team, specs become a shared contract. Less “what I understood was…” and more “here’s what we agreed on”.
If you’re an indie hacker or build your own products, specs are the external memory of your product. In six months, when you come back to a module, you’ll know exactly what it does and why.
The next level: agents specialized in specs
The flow I described earlier can be turned into a reusable agent. You create an agent in Claude Code with the spec-generation skill, give it read, bash and websearch permissions, and configure it to work as an agent and as a subagent (so it can be invoked by other agents in the system).
The result: any user story you feed into the system goes through the same refinement process before a single line of code is generated.
That’s no longer “using AI to program”. That’s having a development system that uses AI.
Conclusion
AI won’t understand your project if you don’t give it structured context. Prompt Driven Development is efficient in the short term and costly as the project grows. Spec Driven Development flips that cycle: a bit more work at the start, much less noise during implementation.
The mindset shift is simple: stop asking AI for code and start giving it intent.
See you on the net.
If you’re interested in harness engineering and how to build development systems with agents, I have more in the pipeline. Follow me on LinkedIn or come back here.