A PRD, a product requirements document, says what to build and why: the user, the problem, the goals, the measures of success. A spec says how it must behave, in precise enough terms to build from directly. The PRD is written for people to agree on before work starts; the spec is what the work is actually executed against. Once an AI agent is doing the building, whatever it runs on is functioning as the spec, whether anyone called it that or not.
The two words get used interchangeably, and most of the time the looseness is harmless. It stops being harmless the moment an agent is building from one of these documents at speed, because then the distinction decides what actually gets made. A PRD aimed at a human reader and a spec aimed at an executor are different artefacts doing different jobs, and confusing them is how teams end up handing an agent a document that was never written to be built from.
What is a PRD?
A product requirements document sets out the case for a piece of work before anyone builds it. It names the user and the problem, states the goal, lists the constraints, and defines what success would look like. Its audience is people: the team that has to agree this is worth doing, the stakeholders who need the why, the designers and engineers who will turn it into something real.
A PRD is deliberately allowed to be a little open. It describes intent and leaves room for the people reading it to interpret, ask questions, and fill gaps from shared context. That openness is a feature upstream, where requirements are still settling and priorities can still move. It becomes a liability the moment the same loose document is handed to an executor that fills gaps too, but not in the way anyone wanted.
What is a spec?
A spec is what the work is actually built against. It carries the precise behaviour the product has to exhibit, in a form an engineer or an agent can build from without guessing what was meant. Where a PRD says "users need a faster way to recover their account", a spec says exactly what happens, in what order, under what conditions, and what counts as the thing being done correctly.
A spec is far less forgiving of ambiguity than a PRD, on purpose. Its job is to remove the room for interpretation the PRD left open, because by the time something is being built, interpretation is risk. Vague language that reads fine in a planning document becomes a defect in a spec, since you cannot build reliably against "handles errors gracefully", and you certainly cannot check whether it was done.
What is the difference between a PRD and a spec?
The shortest version: a PRD is about why and what, a spec is about how it must behave. The PRD justifies the work and the spec governs the building of it. They sit at different points in the process, address different readers, and tolerate ambiguity to different degrees.
| PRD (product requirements document) | Spec | |
|---|---|---|
| Question it answers | Why build this, and what is it? | How must it behave, exactly? |
| Written for | People, to read and agree on | The executor, to build from |
| When | Upstream, before work starts | At the point of building |
| Ambiguity | Allowed, even useful | A defect to be removed |
| Definition of done | Goals and success measures | Behaviour that can be checked |
The two are meant to hand off to each other: the PRD settles what is worth building, the spec turns that into something buildable. In a traditional process they are separate documents, and a fair amount leaks in the gap between them, as the why gets translated into the how by someone reading between the lines.
Is the PRD dead, or is it turning into the spec?
"The PRD is dead" is everywhere at the moment, and it is half right. What is dying is the format: the long requirements document written upstream, signed off, and then never opened again until something breaks. What is not dying is the function. The why behind the work, the decisions and the reasons for them, the shared context that keeps a team building the same thing, all of that still has to live somewhere. As AI moves to the centre of building, that function is migrating into the artefact the work actually runs on, which is the spec.
So the shift is not from PRD to nothing. It is from a document people were trusted to interpret to one an executor is trusted to build from. The loose requirements doc worked because a senior engineer could cover its gaps from experience and ask when something was unclear. An agent does neither. It implements the artefact as written, including its silences, so the parts a PRD was allowed to leave open become the parts that ship wrong. The terminology is converging on "spec" because the spec is where the function now has to do its work. The real question was never whether to write a PRD. It is whether everyone doing the work, people and agents alike, is building from something solid or filling the blanks in alone.
Do you need both a PRD and a spec?
In most real work the two jobs both still need doing, even as the formats merge. Something has to earn agreement that the work is worth building and keep everyone pointed at the same goal. Something has to make that goal buildable and checkable. Skip the first and you build something precisely specified that nobody agreed was worth building. Skip the second and you hand an executor a document full of open intent, and inherit every gap it left.
They do not have to be two separate files, and increasingly they are not. What matters is that both jobs get done: the why is settled and the how is precise. The failure mode is not having one document instead of two. It is having neither job done properly, and calling whatever you hand the agent a spec because it is the document you happen to have.
Which one matters more for AI coding agents?
The spec, because in an AI build the spec is not optional and it is not always the document you intended. Whatever artefact the agent executes on is functioning as the spec, whether it is a real spec, a PRD pressed into service, or a paragraph in a prompt. The agent does not care what the document is called. It builds from what it is given, and the precision of that artefact decides the quality of everything that follows.
An agent implements precisely the instructions it is handed, and not the ones it was not. A senior engineer reading a loose PRD draws on experience to cover what the document left out, and asks when something is unclear; an agent treats each gap as a decision to settle on its own, reaches for the most ordinary answer, and keeps moving. Every omission becomes a choice the agent quietly makes on your behalf, and every ambiguity becomes a defect found later. This is why a good PRD does not save a bad spec: a clear, well-argued PRD handed straight to an agent is still an open document being used as an executable one. The most common way AI builds go wrong is not a missing PRD. It is a PRD doing a spec's job, or a spec that was accurate when written and has since drifted from what is being built. For why an agent wanders off even a good spec, see why AI coding agents ignore the spec; for how a spec stops matching reality over time, see why specs drift from what gets built.
This is the wall the builders we work with keep hitting. They know the difference between a PRD and a spec perfectly well, and they still find that the artefact the agent runs on is stale, or open where it needed to be precise, or disconnected from the codebase it was meant to build. The distinction on paper is clear. Holding a spec to it, as a living thing the build is actually executed against, is the part a document cannot do alone.
Canery is built for that. A Canery spec is structured and fluid at once: precise and checkable enough that an agent can build from it and the work can be measured against it, and alive enough that it stays current as the build moves and keeps holding the why instead of freezing the day it was written. It does that by holding the spec against the codebase it describes, the work as it changes, and the team building from it. That combination is the thing a static document could never be, and it is what lets an agent, or the next person to pick up the work, build from intent that is both exact and still true. The point is not to win an argument about definitions. It is to make sure the artefact your build actually depends on is one worth depending on.
If this is how you want to work
If you want the artefact your build actually runs on to be a real spec, structured enough to build from, alive enough to stay true, and connected to your codebase, rather than a planning document pressed into a job it was never written for, Canery is being built for exactly that. Join the waitlist at canery.ai and be among the first to use it.