Spec-Driven Development with AI: Plan First, Then Let the Agent Build

Vibe coding has real charm. You open Claude Code, type 'build me a login form,' and a minute later you are staring at working code. For a prototype or a weekend project, that is magical. The trouble starts when you try the same thing on a production system with 200,000 lines of code, three teams, and customers who would strongly prefer their payments not go down on a Friday night.

That is where freestyle prompting stops working. An agent is an extraordinarily capable executor, but it is only as good as the task it is given — and 'just do it somehow' is not a task. This is why the best developers in 2026 do not toggle between 'AI vs. no AI' for serious work. They toggle between 'vibe coding' and 'spec-driven development.' Let us look at what that means and when to use which.

What goes wrong when you vibe-code serious work

When you hand an agent a vague brief on a non-trivial task, here is what typically happens: the agent fills in things you never said. It picks a library your project does not use. It changes the data model because it 'felt cleaner.' It solves an edge case you never mentioned and ignores three you actually care about. The code looks fine, it passes the build, and after twenty minutes of reading the diff you either throw it away or spend an hour dragging it back to where it belongs.

The second problem is scope. The agent enthusiastically refactors, renames, and 'improves' files the task should never have touched. The result is a 40-file PR where 35 of those files are noise. Reviewing a PR like that is a nightmare, and this is exactly where security holes and regressions are born — because nobody has the capacity to honestly read 2,000 lines of changes.

What a good spec for an agent looks like

A spec is not a ten-page formal document. It is a clear, concise brief that stops the agent from inventing the things that matter. A good spec for an implementation task contains five things:

• Scope — exactly what to do and what the agent must NOT touch ('modify only endpoint X, leave the data model alone')
• Constraints — which libraries, conventions, and patterns to follow ('use the existing ApiClient, no new dependencies')
• Acceptance criteria — how we know it is done ('returns 400 on missing email, 200 with a token on success')
• File-level plan — which files change and roughly how ('new handler in auth/views.py, test in tests/test_auth.py')
• Test expectations — what should be tested and in what style ('unit tests on validation, one integration test for the happy path')

The trick is that you often do not have to write this spec entirely by hand. Have the agent draft the plan first, then read it and correct it. That is, incidentally, the fastest way to catch a misunderstanding — when the agent writes 'I'll add a new field to the User model' and you know that is off-limits, you catch it in ten seconds instead of after an hour of implementation.

## Task: Rate limiting on the login endpoint

### Scope
- Modify POST /api/auth/login/
- Do NOT change the data model or other endpoints

### Constraints
- Use the existing Redis client (core/cache.py)
- No new dependencies
- Keep the trailing-slash URL convention

### Acceptance criteria
- Max 5 attempts per minute per IP
- On limit: return 429 + Retry-After header
- A successful login resets the limit

### File plan
- core/ratelimit.py — new utility
- auth/views.py — apply decorator to login
- tests/test_ratelimit.py — coverage

### Tests
- Unit: limit triggers after 5 attempts
- Integration: 429 carries the correct header

The loop: plan → review → implement → verify

Spec-driven development has a rhythm. It is not about writing the perfect brief and then vanishing for an hour. It is four phases with human checkpoints in the right places.

1. Plan

Have the agent plan first — no code. Most agents today have an explicit plan mode. The goal is to get a list of steps and affected files on the table before a single line of implementation is written.

2. Review the plan

This is the single most important checkpoint in the whole process. You read the plan, not the code. The plan is ten times shorter than the resulting diff, and reasoning errors surface in it far more easily. You fix the scope, add a constraint, reject an unnecessary refactor. Only then do you give the green light.

3. Implement

Now let the agent run. With a good plan, this phase is largely autonomous — it writes code, runs tests, fixes failures. You do not need to hover over every line, because you set the boundaries up front.

4. Verify

Finally, you verify against the acceptance criteria, not against a feeling. Did the tests you asked for pass? Does the endpoint behave the way the spec said? Does the diff stay in scope? Because you wrote the criteria in advance, review is a concrete yes/no, not a fuzzy 'hmm, looks OK.'

When vibe coding is still fine

This is not a manifesto against vibe coding. Freestyle prompting is a perfectly legitimate tool — just for a different kind of work. Vibe coding makes sense for prototypes, where the goal is to quickly find out whether an idea is even worth pursuing. For throwaway scripts you run once and delete. For personal tools where you are the only user and the only maintainer. For learning a new library, where you just want to see fast how things work.

Reach for the spec-driven approach the moment at least one of these is true: the code will ship to production, more than one person will work on it, it will be maintained long-term, or it does something where a mistake hurts — payments, authentication, customer data. In other words: the higher the cost of error and the longer the code lives, the more it pays to invest in a spec up front.

Conclusion: the plan is the new prompt

The best way to use a coding agent for serious work today is not to write smarter one-shot prompts. It is to learn to write good specs and to run the plan → review → implement → verify loop. The agent takes over the execution. You keep what matters: defining the problem, setting the boundaries of the solution, and deciding when it is done.

Start simple. On your next non-trivial task, have the agent write a plan first, spend ten honest minutes reading and correcting it, and only then let it build. That one extra step in front of you is the difference between 'AI generates code I have to fix' and 'AI builds exactly what I asked for.'