Spec-Driven Development for Agentic Coding

Effective agentic coding is not mainly about better prompts. It is about control.

You want three things at once:

• move extremely fast
• let AI generate almost all of the code
• keep quality, security, and production judgment under human control

Spec-driven development is how you hold that tension. Stronger agents make generation cheaper. They do not decide what you want, what you refuse, or how you will know the result is good. Specs are the control loop.

Why Vibes Coding Fails

When a model writes code without enough structure:

• requirements stay fuzzy
• tradeoffs stay unspoken
• constraints get forgotten mid-generation
• teams ship the first plausible answer instead of the right one

Better autocomplete and better agents improve speed. They do not create shared intent. If your team cannot point to what "done" means before generation starts, the model is guessing in your name.

Make Generation the Last Step

A useful pipeline looks like this:

1. Thought dump. Capture raw ideas, constraints, edge cases, and half-formed opinions. Do not force structure yet.
2. PRD with clarification rounds. Have an LLM ask clarifying questions across a few rounds, then turn the dump into a product requirements document.
3. TRD with repo context. Combine the PRD with code and architecture context. Clarify again. Produce a technical requirements document.
4. Experiments when needed. Run benchmarks, spikes, or comparisons when a design choice is still uncertain.
5. Phased implementation plan. Break the TRD into small phases that stack. Each phase should be reviewable and testable. Prefer one phase per commit, one feature per PR.
6. Code generation. Only then generate implementation, with the plan and context as the source of truth.

Each step produces an artifact the next step can trust. The model stays busy generating. People stay responsible for intent.

Force the Hard Questions Early

Clarification rounds are not only for cleaner documents. They make your team answer things that are easy to skip once someone is already coding:

• what exactly are we building
• what are we not building
• what happens at scale
• how data migration works
• how we deploy
• how we verify after deploy
• how we roll back
• how security is handled

Build those questions into the process. A short security checklist, drawn from past incidents and reviews, works much better when the pipeline expects it. The awkward checks become normal, not optional.

There is a second payoff: people learn during the pipeline. By the time coding starts, the team usually understands the problem better than when they began.

Productize Context

A pipeline fails if the model has nowhere stable to look. Maintain markdown your team can point at:

• products and feature areas
• DB schemas
• services and ownership boundaries
• API surfaces
• conventions: what you prefer, what you avoid, what "good" looks like here

Code shape matters too. Large files fight context windows and make generation worse. Smaller, focused modules make agentic coding more usable for both humans and models.

When you ask for implementation, be explicit:

• include dependency changes
• include class and DB schema changes
• call out new or updated libraries
• keep the design SOLID and testable
• treat tests as part of the delivery, not an afterthought

Most of the hard work is not prompt craft. It is writing context, watching where generation drifts, rewriting the context, and repeating until the model stays inside your standards.

Resolve Unknowns Before You Commit

Not every project needs a spike. Some do.

Before locking a library, plugin, or approach, ask for comparisons. Sometimes that is reading docs. Sometimes that is a small benchmark or prototype.

If the design depends on an unknown, write the unknown down and resolve it before spending a full implementation cycle on the wrong path. A confident TRD is useless if it is still a guess.

Keep the Spine When Tools Change

Internal generators, Tab complete, agents: the surface keeps moving. Keep the same spine underneath:

• PRD
• TRD
• experiments when needed
• implementation plan
• phased execution

Better agents make longer changes practical. They still do not replace a clear plan.

What Effective Agentic Coding Looks Like

1. Specs before code. Dump thoughts, then force clarity into a PRD and TRD.
2. Phases before pull requests. Make each step small enough to review, test, and reverse.
3. Context before clever prompts. Schemas, services, APIs, and conventions should be written down.
4. Modular code before magic. Focused files make both humans and models better.
5. Comparisons before commitment. Do not pretend uncertainty is a design decision.
6. Checklists before "looks good". Scale, migration, deploy, rollback, and security are not optional add-ons.
7. Humans own judgment. Models generate. People decide.

Agentic coding fails when people treat the model as the source of truth. It works when people treat the model as a very fast implementer working inside a clear, testable plan. Specs are how you keep that boundary.

I arrived at this the hard way while shipping with AI coding agents at BlogVault from about 2023 to 2025. I am no longer there, and none of this is an official company write-up. I still use the same pattern in my own work, including on dharmiq: clarify product intent, write the technical requirements, then implement in phases against written principles and plans.