A good spec for AI coding agents is one that stays connected to the work instead of sitting beside it. It knows what already exists in the codebase, so the same thing is not built twice. It stays current as the build changes, so the plan and the product do not drift apart. And it makes done something that can be checked rather than argued. Most specs fail because a static document can do none of this.
Writing a good spec has never been the hard part. Keeping it true to what gets built is. A spec starts as an accurate picture of the plan, and then the work begins. Decisions move into Slack, the design shifts, an agent takes a shortcut, and within a few days the document on file and the product being built have quietly come apart. Nobody decides this. It happens because the spec is a fixed description and the work is a moving thing. With AI doing the building, the gap opens faster, because the agent executes at a speed no document was ever written to keep up with.
Why do AI agents build things that already exist?
A spec is a snapshot. A codebase is a moving target. The spec describes what is wanted and says nothing about what is already there, so an agent reads the spec, never the system around it, and rebuilds a function that already exists under a slightly different name. The better agents get at executing, the faster this happens. The result is more code, more duplication, and a widening gap between what the spec says and what the product actually is, with no point in the process where anything checks.
Why do specs drift from what gets built?
Specs do not drift because people are careless. They drift because the work leaves the document. A spec is written, and then the real decisions happen somewhere else: a thread, a call, a review comment, a quick fix an agent made overnight. None of it travels back into the spec, because updating the document is more effort than the moment allows, and starting fresh next time feels easier than reconciling what changed. So the spec freezes at the version its author last touched and slowly stops describing anything real. The next person to pick it up inherits a document that looks authoritative and is quietly out of date.
Isn't a spec just a PRD?
The words get used loosely, so it is worth being precise. A PRD, a product requirements document, traditionally describes what to build and why: the user, the problem, the goals, the success measures. It is a planning artefact, usually written upstream, and it is meant to be read by people. A spec, in the sense that matters once AI is doing the building, is the thing the work is actually executed against. It carries the precise behaviour the product must exhibit, in a form an agent or an engineer builds from directly.
In a traditional process the two are separate documents that hand off to each other, and a lot leaks in the gap between them. When we talk about a spec at Canery, we mean a single artefact that carries the intent and the executable detail together and stays attached to the work, rather than a planning document that sits to one side of it. The distinction matters because in an AI build, whatever the agent runs on is the spec, whether anyone called it that or not. If that artefact is a stale document, the build inherits everything wrong with it.
How is this different from spec-driven development?
Spec-driven development is the name for the shift this whole article sits inside. Rather than prompting an agent and hoping, you write the spec first and let the spec drive what gets built. It puts the spec at the centre and treats it as the source of truth, and it is the right instinct. Canery sits inside that world.
The difference is where it stops. Spec-driven development, as most tools practise it, runs in one direction, from spec to code. The spec is an input to a build, and once the code is generated its job is largely done. That leaves every gap above still open. The spec still has to be kept alive, still has to know what already exists, still has to survive a handoff, and nothing in it says whether what got built was worth building in the first place.
Canery treats the spec as the centre of a loop rather than the start of a line. The spec is where real signal becomes a decision, what ships writes back against it, and what the team learns feeds the next one. Spec-driven development gets a good spec to the code. Canery is built so the spec keeps earning its place long after the code is written.
So what does a good spec actually do?
A good spec does the one thing a static document cannot. It stays connected to the work as the work changes. It knows what already exists, so the same thing does not get built twice. It stays current as the build moves, so the gap between plan and product never opens. It makes done something that can be checked rather than argued. And it belongs to the team rather than to one person's machine, so handing it over does not mean losing the reasoning behind it.
This is the wall the builders we work with keep hitting. The strongest of them have built genuinely impressive spec setups of their own, and they still lose the thread the moment the work moves or a second person needs in. The setup is brilliant and it is single-player, and it evaporates exactly when it is needed most.
| Once the work is moving | A spec in a doc (Obsidian, Notion, Confluence) | A Canery spec |
|---|---|---|
| Knows what already exists in the build? | No | Yes |
| Stays true as the build changes? | It drifts | Yes |
| Tells you it's actually done? | A judgment call | A clear answer |
| Survives being handed to someone else? | The context leaves with them | It stays with the work |
Canery is built so the spec is that connected, shared, living thing instead of a file that rots. It does that by holding the spec against the codebase it describes, the work as it changes, and the team building from it, so the same thing is not built twice, the plan and the product stay in step, and the reasoning does not walk out the door when one person does. The spec stops being a description you write and abandon, and becomes the thing the whole build runs on and learns from.
If this is how you want to work
Specs do not have to rot. If you want to write specs that know your product, hold up as the build moves, and get sharper every time you ship, Canery is being built for exactly that. Join the waitlist at canery.ai and be among the first to use it.