Spec-driven development is the practice of turning a feature request into precise, structured specifications before any code is written - so the implementation step, increasingly done by AI agents, has no ambiguity to guess at. Well-formed specs are what make agent output reliable: the clearer the spec, the safer the build. Vague inputs produce vague - or confidently wrong - outputs, no matter how capable the model. Specs are the interface between intent and execution.
This isn't a new idea. Martin Fowler and the broader software engineering community (martinfowler.com) have argued for decades that ambiguity in requirements is the single biggest source of rework. What's changed is who's reading the spec. It used to be a human developer who could ask a clarifying question in Slack. Now it's often an AI agent that will happily fill gaps with plausible-sounding assumptions and ship them straight into a pull request.
What Is a Spec, and What Should It Contain?
A spec is a document that defines exactly what should be built, how it should behave, and what "done" looks like - with no room for interpretation on the details that matter. A good spec for agent consumption typically includes:
- Scope statement - what's in and explicitly what's out
- Acceptance criteria - testable conditions, not adjectives like "fast" or "intuitive"
- Data contracts - input/output shapes, types, edge cases, error states
- Dependencies - which services, endpoints, or components it touches
- Non-functional constraints - performance budgets, security requirements, backward compatibility
If a spec can be satisfied by two meaningfully different implementations, it isn't finished yet.
How Do PRDs, ADRs, and Specs Fit Together?
Spec-driven development works as a hierarchy, where each layer resolves a different kind of ambiguity:
- PRD (Product Requirements Document) - resolves ambiguity about why. What problem are we solving, for whom, and what does success look like? (See: Auto-Generate a PRD, Day 9.)
- ADR (Architecture Decision Record) - resolves ambiguity about how, structurally. Which pattern, service boundary, or data model are we committing to, and why not the alternatives?
- Spec - resolves ambiguity about exact behavior. Given the PRD's intent and the ADR's architecture, what precisely should this component do?
- Tasks - resolves ambiguity about sequence and ownership. What are the discrete, independently verifiable units of work, in what order?
Skip a layer and the ambiguity doesn't disappear - it just resurfaces downstream, usually inside the agent's implementation, where it's more expensive to catch. This is the same layering logic covered in Automating Feature Development (Day 6): the pipeline only stays reliable if each artifact does its job before handing off to the next.
Why Do AI Agents Fail on Vague Specs?
Agents don't fail randomly on vague specs - they fail predictably, in three ways:
- Silent assumption-filling. An agent told to "add pagination" will pick a page size, a cursor strategy, and an error format on its own. It won't flag the choice as a guess.
- Scope creep or scope collapse. Without explicit boundaries, agents either over-build (adding config options nobody asked for) or under-build (missing an edge case that was implied but not stated).
- False confidence. Large language models generate fluent, structured output regardless of whether the underlying spec was solid. A vague spec doesn't produce visibly weak code - it produces code that looks finished and isn't. That's the dangerous failure mode: it passes a skim review.
This is well documented in the growing body of research on LLM-based software agents (see recent papers on arXiv) - task success rates correlate strongly with specification precision, more than with model size or prompt cleverness.
How Do You Validate That a Spec Is Complete?
You can check spec completeness deterministically, without relying on gut feel. A spec is agent-ready when it passes these checks:
- The two-implementation test: could two competent engineers build meaningfully different things from this spec? If yes, it's underspecified.
- Every acceptance criterion is testable. If you can't write an automated test for a line in the spec, rewrite the line.
- Every input has a defined error path. Null, empty, malformed, oversized, unauthorized - each needs a stated behavior, not an assumption.
- No open questions remain in the document. A spec with a "TBD" is not a spec, it's a draft.
- It references the ADR it depends on. A spec that contradicts the architecture decision it inherits from is a bug waiting to happen.
Teams that treat this as a checklist rather than a vibe check catch far more ambiguity before an agent ever opens an editor.
Where Should Humans Edit - the PRD, the Spec, or the Code?
Spec-driven development doesn't remove humans from the loop; it moves them to higher-leverage points and makes their edits cheaper. The general rule: edit as far upstream as the problem originates.
| If the problem is... | Edit here |
|---|---|
| Wrong feature or wrong priority | PRD |
| Wrong technical approach or pattern | ADR |
| Wrong behavior, missing edge case, unclear acceptance criteria | Spec |
| Wrong sequencing or task boundaries | Task breakdown |
| Style, naming, or minor logic tweak | Code, post-generation |
Editing code to fix a spec-level problem is a trap - it patches one symptom while leaving the same ambiguity to cause the next bug. Editing the spec instead fixes it for every future implementation that reads that document, including the agent's next pass. This is also where human approval gates matter most, the same checkpoint model described in How AI Agents Open PRs (Day 7).
How Is This Different From Vibe Coding?
Vibe coding is prompting an AI with a loose, conversational description and iterating on whatever it produces until it looks right. It works for prototypes and throwaway scripts. It breaks down in production systems because "looks right" and "is correct" diverge fast - especially on edge cases, security, and integration behavior that don't show up in a casual demo.
ThoughtWorks Radar (thoughtworks.com/radar) has tracked this shift explicitly - flagging spec-first and structured-prompt workflows as the maturity path away from ad hoc AI coding as teams move from experimentation to production reliance on agents. As agentic coding (see What Is Agentic Coding?, Day 4) becomes the default way code gets written, the spec is what separates a system you can trust from one you're hoping works.
Where Does Feedback Fit Into the Spec Pipeline?
Specs don't start from nothing - they start from a request, usually a support ticket, a sales call note, or a churn-risk comment. The weakest part of most pipelines isn't the coding step, it's the translation from raw feedback into a spec precise enough to build from. VocxAI turns customer feedback into shipped code - it ingests signals from your support and feedback tools, prioritises what to build, and runs an AI agent pipeline from PRD to pull request with human approval at every gate. That means the PRD → ADR → spec → task chain isn't a manual authoring exercise every time; it's generated from real signal and refined by humans at the checkpoints that matter, using version control and PR workflows consistent with standard practices documented on GitHub.
FAQ
What is a software spec?
A software spec is a document that defines the exact expected behavior of a feature or component - inputs, outputs, edge cases, and acceptance criteria - precise enough that an implementation can be objectively verified against it.
Why do AI agents need detailed specs?
Agents fill gaps in instructions with plausible-sounding assumptions rather than flagging uncertainty. Detailed specs remove those gaps, so the agent's output matches intent instead of a guess.
How is spec-driven development different from TDD?
TDD writes tests before code to drive design at the implementation level. Spec-driven development operates a layer higher - it defines the full behavioral contract (including scope, edge cases, and non-functional constraints) that tests are then written to verify. Specs and TDD are complementary, not competing.
Who writes the specs - human or AI?
Increasingly, AI drafts the first version from a PRD or feedback signal, and a human edits it at the PRD, ADR, or spec layer before it reaches implementation. The goal is fast drafting with human judgment at the decision points, not full automation of the thinking.
What makes a spec 'agent-safe'?
An agent-safe spec has no open questions, testable acceptance criteria, defined error paths for every input, and explicit alignment with its parent ADR - meaning two different agents given the same spec would build functionally equivalent systems.
See how VocxAI builds this for you
VocxAI connects your customer signals to your revenue data and surfaces a ranked, revenue-weighted product backlog - automatically, every week.
Join the private beta