Spec driven development with ai means you write the contract before the agent writes the code. No vibes, no chat summaries. A short versioned file naming the outcome, the constraints, the exclusions, and the tests that decide whether the build passed. I run every serious build this way. Rework has dropped to a fraction of what it was. The spec comes first.
An agent without a spec drifts. The requirements lived in your head, or in scattered chat messages, and every fresh session re-invents them a little differently. Spec driven development with ai moves them out of chat and onto disk, where context compaction cannot eat them. Below are the eight rules, the spec file anatomy, and a worked example.
The trend is not mine alone. In a January 2026 developer discussion on agent build failures, an engineer said spec-driven development crystallizes the context you hold about the code into something the agent can use (source: stackoverflow.blog, 28 Jan 2026). Spec driven development with ai is the formal name for writing the target down before anything touches the repo.
Spec driven development with ai, defined in plain words
The traditional spec is a document humans read before coding starts. It is usually long, and stale by the second sprint. The AI-era version differs in one respect: in spec driven development with ai, the spec is the primary input the agent works from, reread at every step.
Spec driven development with ai keeps three traits the old-style document lacks. It is versioned like code. Every requirement is checkable. The relevant lines re-enter with every task instead of a one-time briefing.
Google’s Gemini developer docs reach a similar point from the prompting side: structure requests so context, task, and constraints stay separated and explicit (source: Google AI for Developers docs). A prompt evaporates with the session. A spec file survives, and the next session loads it first.
Why vague prompts produce drift (Monday feature, Wednesday rewrite)
Every builder meets the Monday feature that becomes the Wednesday rewrite. Mine happened during the password intelligence plugin work. On Monday I asked for the strength meter helpers and got clean async functions wired to the existing UI layer. On Wednesday, in a fresh session with no written spec, the same agent rebuilt the area with promise chains and inline DOM calls that fought the stylesheet. Two different codebases pretending to be one, and I spent an evening merging them.
That session style inconsistency shows up across teams too. One session picks async and callbacks, the next picks promise chains: identical features, opposite approaches (source: builder.io limitations analysis). The deciding preference was never disk-resident. It was one chat message from three days earlier, dead weight by Wednesday. Chat is not a spec. Spec driven development with ai ends that mechanism by itemizing code style rules beside behavior, so every session reads the same lines and Wednesday builds like Monday.
A second drift source matters as much. After roughly two thirds of the context window fills, agent reliability degrades. Builders call that context rot, and the requirements from message one weaken first. Spec driven development with ai re-issues the decisive lines with every bounded task, so they sit near the model’s attention instead of forty exchanges behind it.
caption: The full loop on one card: outcome, constraints, exclusions, test-shaped criteria, version the spec, lock it, then build against it.
Rule block 1: outcome, constraints, exclusions
Rules one through three shape the top of every spec. They take about five minutes. They decide whether the agent builds your feature or its own idea of it. This block is where spec driven development with ai pays its first dividend, before any code exists.
Rule 1: the outcome section. One short paragraph naming the user, the job, and what done means. Spec driven development with ai keeps it readable because the consumer is an agent re-reading mid-build, not a committee. A spec line of mine read: a visitor who ran a password check can copy a plain text summary of the results to their clipboard, the copy confirms visually within one second, sanitization follows the existing pattern. Three sentences, zero reopen. That is the whole idea.
Rule 2: the constraints list, the walls the agent builds between. Exact lines pay twice. They pay while the agent writes, and again during audit when I check the build against the file. Mine named the runtime target, the existing sanitization helper, a ban on new network calls, and the one-second feedback rule after a click.
Rule 3: the exclusions list, also called non-goals. I write what the build must not do, even when it feels obvious. The same spec said: no export to file, no settings page entry, no changes to the meters themselves, no new dependency. An agent that reads that list will not propose a clipboard library or an options panel. Exclusions are where spec driven development with ai stops scope creep before code exists.
All three blocks convert preference from memory into numbered text. The agent gets something to obey. You get something to verify.
Rule block 2: acceptance criteria as test names
Rules four and five turn the spec from description into checklist. This block carries most of my quality gains. The shift is small: criteria written in the shape of a test.
Rule 4: write each criterion exactly like a future test name. Not “copying should work well”, but four separate lines. Given a completed check, clicking copy writes the summary text to the clipboard. Given an empty results state, the copy button renders disabled. Given success, a visible confirmation appears within one second. Given clipboard permission denied, the button shows an error hint and the summary stays on screen.
Spec driven development with ai reads this section differently. The agent is the consumer here. “The copy confirms within one second” is implementable. “User friendly copy behavior” gets repainted once per session.
Rule 5: map every criterion to a named test and a named artifact. My criteria section ends with a small table: criterion number, test name, evidence path. Anything that cannot enter the table leaves the spec. Ten checkable lines beat twenty beautiful ones, because spec driven development with ai turns audit into a reading exercise instead of a debate.
One caution. Do not pad the criteria. Skip any line that exists only to sound thorough. Each extra untestable line is drift fuel.
caption: Each criterion line pairs with one test name and one evidence path, so any line can be answered pass or fail from a record rather than from memory.
Rule block 3: version the spec, then lock it
Rules six through eight treat the spec the way developers treat code: version numbers and an approval gate. Skipping this block is why most specs rot into fiction within two weeks.
Rule 6: put a version header on top. Mine carries the spec version, the dates, and the stack facts with a check date each. During the site build, a header note saying delivery limits were checked against provider docs on 16 Oct 2026 saved a rebuild two months later. The memory was gone, but the record was not.
Rule 7: lock the spec before implementation and log who approved it. Spec driven development with ai borrows plan lock from my governed loop here: version, date, approver, then treat editing as an event. Locking matters because silent spec edits are invisible drift. An agent updates one requirement, persuades itself it was an improvement, and the tests still pass against a target nobody agreed on. After the lock, a change needs a change log note, a fresh approval, and a higher version number.
Rule 8: keep the locked spec the single source of truth and cite it by version in every task and report. When audit scores the build, it quotes spec version 1.2, not “the requirements as we discussed”. The lock also earns a clean reset across sessions. When a run stops mid-task, the locked file plus the change log are the handoff record, which beats an inbox of half-remembered chat instructions. One file, one version, one truth.
caption: The lock gate in one frame: version number, dated stack facts, an approver line, and a change log that opens only after approval.
How an agent reads a spec (practical anatomy)
Open any spec file the way the agent will meet it: top to bottom, one pass, no memory of prior reads. That assumption drives the anatomy I use for every spec written under spec driven development with ai.
Header comes first, always. The agent needs the governing version in context before any requirement line. Dated stack facts next: runtime, key library versions, verified limits with their check dates. Then the outcome paragraph, constraints, exclusions, and the criteria table. By the time the agent reaches the criteria, it already knows the walls and the target.
Repetition is a feature, not waste. I copy the relevant constraint and criterion lines into every task brief. Spec driven development with ai makes that repetition cheap on purpose. A ten minute task carrying six familiar lines costs almost nothing, and it removes the main failure window.
Language decides agent behavior more than length does. Write imperative, checkable sentences. “The console lists the file name and the row count” is a line any model can honor. “Responsive feedback” is a mood it repaints each session. Where the spec touches code, name real files and functions, because vague references to “the existing utilities” send the agent hunting. In spec driven development with ai, the file’s vocabulary is law.
caption: Header, dated stack facts, outcome, constraints, exclusions, criteria: the reading order an agent follows, with task briefs repeating the relevant lines per task.
Worked spec: one small feature end to end
Here is the full method on a small build. It is a support console on my own stack, and it needs a reissue button for a failed customer list export. Small enough for one evening. The discipline still earned its keep, as it does on every spec driven development with ai build, small or large.
The spec header read: version 1.0, dated, approver me, and an export cap of 50,000 rows per run, noted from provider docs with the check date. Outcome: a support agent can reissue a failed customer list export within thirty seconds, and the console shows the download link plus the exact row count. Constraints: the export call uses the existing query module, the file lands in the existing downloads folder, one log line per reissued export. Exclusions: no scheduled exports, no new file formats, no email delivery of the file.
Then three criteria, each shaped as a named test compiled before any code existed. The agent worked directly against the criteria table. It asked exactly one clarifying question the whole time: should the log line record attempts or only successes.
The diff review caught one extra, a seed helper for sample rows. It was rejected without argument, because exclusions covered additions. Tests ran 12 of 12, then 13 of 13 after I added the missing guard test. The verdict was pass with one named limitation: the row cap still applies, so very large lists stay manual until next sprint. That limitation went into the release note, beside the spec version. Two focused hours, three defects caught early, zero reconciliation fights. That is spec driven development with ai on something small: a written pact with your future self, not bravado.
caption: One real spec card: dated export row cap, outcome, three constraints, three exclusions, criteria that became three named tests.
The engine angle: plan lock before implementation
The SOVEL Copilot Engine turns this discipline into a stage, which is what makes spec driven development with ai trustworthy at scale. The engine is a local workflow controller, not an AI model. It walks a build through named stages: IDEA, RESEARCH, ANALYSIS, PLAN, PLAN LOCK, IMPLEMENTATION, AUDIT, then FIX and RE-AUDIT, a FINAL REPORT with EXPORT, and a release gate. You bring your own API keys, and provider cost sits outside any license.
PLAN LOCK is where rules six and seven live. The plan cannot leave the lock stage without approval recorded beside it. That is plan lock doing for builds what spec driven development with ai asks at the file level. Audit runs on an independent path. The checking role reads with a ruler instead of grading its own essay. Failed findings route to bounded fix work, then RE-AUDIT verifies the repair.
Everything lands on disk. SQLite-backed local state and a hash-chained event ledger record what ran, when, and against which plan version. Reports export as JSON, Markdown, HTML, PDF, DOCX, or EPUB. A pass report is input to the release gate, not a substitute for it. Demo mode runs the same stages. Output stays labeled as demo. All licenses run the same engine. Personal, Pro, and Agency differ in seats and commercial terms, not in gates.
Limits
Spec driven development with ai has honest boundaries, and pretending otherwise sells a method that fails in the field. A spec fixes alignment. It does not fix judgment. One tidy paragraph in front of a weak idea still produces a weak build, just documented well. The outcome section exists to force your thinking, not to bless whatever you first typed.
It also cannot force obedience. Models vary in how carefully they honor written constraints, so the spec improves odds while diff review, tests, and audit stay mandatory. Provider costs and API limits sit outside any spec. Generic AGENTS.md files cover style conventions, but they rarely carry per-feature criteria. That gap is precisely what spec driven development with ai fills.
Finally, this is a discipline for controlled builds. One line scripts and throwaway probes do not need it. Forcing a five block spec onto a ten line script is process theater.
FAQ
What is spec driven development with ai?
It is the practice of writing a versioned, checkable spec before an agent writes code. The outcome, constraints, exclusions, and acceptance criteria live on disk in one file the agent rereads at each step.
How do I write a spec for an AI coding agent?
Use five blocks in this order: version header with dated stack facts, one outcome paragraph, a constraints list, an exclusions list, and acceptance criteria written as test names. Lock the version before implementation and log later changes as numbered revisions.
Why do AI agents drift from requirements?
Requirements kept in chat decay as the context window fills. Spec driven development with ai removes that decay because the decisive lines re-enter context with every task brief and survive handoffs between sessions.
Can you give a spec driven development with ai example?
A support console reissue button. The outcome set one job and one time limit, then three criteria became three named tests. Exclusions rejected one unrequested helper, and the build closed to a pass verdict with a named limitation in two hours.
How long should the spec be?
One screen. Header, outcome, constraints, exclusions, criteria, each numbered. Longer specs quit getting reread, and a spec nobody rereads is a decoration with a version number.
Does the spec replace testing?
No. Test-shaped criteria make testing cheaper and fairer, but the run evidence, the diff review, and the audit still decide the verdict. A spec states the target. Tests prove whether the build hit it.
Eight rules, one screen, one versioned file your agent cannot quietly drift from. Write the spec first on your next build, lock it, and let the criteria cut the arguments. The engine that runs this shape stage by stage, plan lock through release gate, is documented on the engine page if you want the loop wired for you.
the scope control rules for AI agents
the seven step AI coding workflow
the governed vs automation comparison
(Self-report: estimated body word count ~=2760, focus keyword exact occurrences 27 in body including H1, 5 inner links, 2 external links, 5 figure blocks, last figure renamed to spec-driven-development-worked-spec-card.webp.)