The Spec Is Not a Document

Three to five specs a day, sustained for weeks. The pace nobody used to be able to hold. The shape the artefact had to become to make it possible. Six primitives, not one document. Decisions as records, not paragraphs. The bookend that closes when the test runs.

Full-throttle AI-native teams complete three to five specs per day per human. That is an insane pace. Unheard of in traditional software development and unsustainable without a harness around the AI agents.

I have been shipping software for thirty-five years, and until a year or so ago I had never seen a team hold anything close to that rate. Three to five complete units of work per engineer per day, each one specified and built and verified, sustained week after week, on a codebase the team can still reason about a year later. That is the cadence I now watch our own team move at. It is not a vibe-coding fluke. Vibe-coding sprints can produce that rate, briefly, before the codebase becomes incoherent and the team can no longer reason about what was built. The cadence I am describing does not do that, and it does not do that because of a single structural change in the shape of what a specification is. That change is the thing we set out to make possible when we built Memex.

A specification used to be a document. I have reviewed and written thousands of them across that career, in every shape our profession has reached for: Word documents, design docs, RFCs, ADRs, Linear tickets with attached PDFs, Confluence pages with twenty comments down the side. Almost none of them were read carefully by the person who built the thing. That was fine for all those years, because the person who built the thing had sat in the planning meeting and could fill in the gaps from instinct. It is not fine any more. The participant building the thing is increasingly an agent, and the agent did not sit in the meeting.

So the specification has had to become something else. Not a tidier document. Not a more rigorous document. Not a document at all. A database.

The spec an AI coding agent needs is a database, not a document.

That is the move this chapter is really about, and it is bigger than it first sounds. A document is a piece of prose with sections and headings. An agent loads the whole thing, tries to parse it, and acts on whichever bit it noticed first. A database is something else. Records have types. Records have status. Records refer to other records. A query against the database returns exactly the shape of information the caller needed, whether the caller is a human reading the spec in a browser or an agent loading the resolved decisions for the task it has just claimed. The artefact stops being a long piece of prose anyone can ignore, and starts being a structured object the work runs against.

Six primitives, not one document

What sits in the database is six distinct types of record, and AI spec-driven development comes from giving each one its own life. They are not bullet points inside the spec. They are first-class objects, with their own statuses, their own histories, their own queries.

The narrative. What is being built, and why. This is the closest thing in the new shape to what a traditional spec used to be: ordered sections of prose covering overview, design, architecture, risks, anything else the team needs. The difference is that the prose is no longer the whole spec. It is one primitive among six, and the others are joined to it. The narrative is just where the spec starts.

The decisions. Every non-obvious choice the build will depend on, written as its own record with its own handle. Should the cursor encode an offset or an opaque token? Should retries back off exponentially or linearly? Should we soft-delete or hard-delete? Each of those is a decision record with options, rationale, the chosen path and the reasons the others were rejected. Decisions are addressable: a human or an agent can refer to dec-3 on the auth spec and both parties know exactly what is meant. When an agent encounters a decision the spec did not anticipate, it does not invent. It writes a candidate decision into the database for human review, and the build pauses or continues with the resolution noted as provisional.

The acceptance criteria. Observable, testable conditions, written into the spec, that define what “done” actually means. A returning user with an expired session sees the sign-in page, not an error. That sentence is a unit test, an integration test and a smoke test waiting to be linked back to it. There are two flavours: scope criteria written by the manager up front to define the outcome, and implementation criteria spawned from each resolved decision to prove the chosen option was honoured. Each criterion has its own live status, and the status is not self-reported. It is derived from CI.

The tasks. A directed acyclic graph of the work, not a flat backlog. Each task carries a goal, the acceptance criteria it is meant to satisfy, and explicit dependencies on other tasks and on resolved decisions. The agent asks the database which tasks are ready, and the database returns only the ones with no open blockers. There is no manual triage. The graph knows what is unblocked, and the agent picks up what the graph says is unblocked.

The issues. When the agent runs into something it cannot resolve mid-build, it does not bury the problem in a transcript that nobody will read again. It writes an issue record against the spec, with the kind, the severity, the body of what went wrong, and a link to the task that surfaced it. Issues materialise in the user interface where a human can see them at a glance. Where the agent has been trying to do something a human ought to decide, the system can promote an issue into a new task with a verifying acceptance criterion attached, and the issue closes itself when the task completes and the test goes green.

The emit tokens. This is such a divergence from the norm it is easy to miss. An acceptance criterion does not know whether it is currently true until something tells it. The mechanism that does the telling is small enough to fit on a line of code. Inside the test file, the agent writes tagAc(’spec-11/acs/ac-1’) at the top of the test. When the test runs in CI, the assertion library reads the tag, calls the spec database, and emits a token recording that ac-1 has just been verified by a passing test, with a timestamp. The acceptance criterion’s status is derived from the most recent emission against it: verified, failing, stale or untested. Nobody is updating anything by hand. The board on the spec page is what CI has reported, and it is current to the second.

Those six primitives, sitting in the same database, joined to one another, are what a specification has become in an AI-first team operating on full throttle. Every decision links to the criteria it spawned. Every criterion links to the tasks that satisfy it and the tests that emit against it. Every issue links to the task that surfaced it. The artefact is no longer a piece of prose. It is a graph the team and the agents read and write together, and it is what makes the cadence at the top of this piece survivable.

Let’s turn to the phases of the process.

Specify

You start with the narrative, your goals and any constraints. You run the spec past the system, and the system pulls out every implicit decision hiding inside it. Each one becomes a candidate decision: surfaced, with options laid out, with the trade-offs articulated. The team works through them, choosing the path on each one as a deliberate act. As decisions resolve, the system spawns the implementation acceptance criteria they imply, so each resolution comes with its proof attached.

Humans comment and prompt, agents do the writing and the laborious work of linking the narrative to the decisions and the acceptance criteria. The division of labour matches the division of skill: the human carries the judgement, the agent carries the bookkeeping, and the artefact stays current with both.

When the human looks at the spec and is ready to move it forward, the system does not let the move happen on a vibe. It runs a deterministic readiness assessment: are all decisions resolved, are the criteria well formed, are open comments cleared. If they are not, the move is refused with reasons. If they are, the spec advances to the build phase and the tasks crystallise out of the resolved decisions.

The first time you go through this on a real piece of work, the surprise is how much of the argument that would have happened in code review has just happened in the spec instead. The hard conversations move three days earlier and cost less than they ever did. That on its own is worth the discipline, even if the agent half of the work did not exist.

And the next spec the team writes is easier than the first, because every decision they have previously resolved sits in the database, vector-indexed, available to inform the new one. The system understands the lineage of choices over time: a new decision that supersedes an old one does not erase it but inherits from it, and the older record stays queryable under the new context. The human remains in control of every move forward. What changes is that the team’s history finally starts working for the team.

Build

The build, with a properly specified database behind it, is the cheap step. An agent connected over MCP queries the spec for the ready tasks, claims one, and receives a scoped context payload: the narrative section it needs, the decisions that constrain the work, the criteria the task is meant to satisfy. Not the whole document. The slice of the graph the task actually requires.

What is genuinely new is what happens when the agent encounters something the spec did not anticipate. A decision it has to make to keep going lands as a candidate in the database. An unexpected problem becomes an issue. The agent does not invent silently, and it does not stop forever. It writes the new record, and continues if it can, and escalates if it cannot. The team approves or rejects the candidate decision; the issue surfaces in the interface; the work threads back together.

By the time the build is finished, the spec contains every decision the team and the agent made between them, every issue raised and resolved, every task completed. The spec is not consumed by the build. It is fed by it. What you have at the end is a contemporaneous record of how the work actually happened, which is the thing every architecture-decision-record process I have ever run has tried and failed to produce by hand.

Verify

Verify phase is where the bookend closes, and the closing is mechanical rather than ceremonial.

Every acceptance criterion has been tagged in code. Every tagged test, when it runs in CI, emits a token to the database. The spec page shows the live status of each criterion: verified, failing, stale or untested. “Done” is no longer a judgement call by the engineer who wrote the code or the engineer who reviewed it. It is a fact derived from the most recent CI run.

Months later, when a change in some other spec breaks an acceptance criterion from this one, CI runs the test, the test fails, the emit token records a failure, and the criterion flips from verified to failing on its own. Nobody has to remember to look. The protection lives in the database, and the database is awake.

In the past, the question is this feature done? has been answered by a slightly fuzzy consensus between the engineer, the reviewer and the product manager. Everyone has had a version of the conversation that goes: I think it is done, but I want to look at one more edge case. A verify phase wired into CI removes that conversation. The criteria are either met or they are not. If there is a disagreement, it moves back to whether the criteria themselves are right, which is the disagreement that should be happening, in the spec, before the build began.

What this is not

Spec-driven development is not new in name. Tools have existed that generate a Markdown spec from a conversation, hand it off to a coding agent, and walk away. The Markdown ages out the instant the first commit lands, drifts from the code within a week, and ends up exactly where the Word documents used to live: in a drawer, unread. The difference is the database. A document cannot tell you it has been verified. A document cannot kick back an issue. A document cannot know it has been overtaken by a change in some other spec. The shape of the artefact has to change, not the prose style of the spec it is replacing.

It is also not waterfall, although it touches the same nerve. Waterfall failed because the cost of changing a specification later was supposed to be higher than the cost of getting it right up front, and in a world where implementation was the slow part, that calculation never quite worked. The calculation has inverted. Implementation is cheap; specification is the expensive part. The careful work at the front of the board now pays back where it used to merely defer. Waterfall, brought back, but only the half that was ever right.

Flagging the obvious. This is the part of the thesis we are building a product around at Mindset AI, called Memex AI. I will keep writing about it whether or not you ever try it. The shape of the problem will not change.

Memex AI is the harness we have just shipped around the loop I have described. The six primitives are records in a Postgres database with pgvector for semantic search. The agent connects over MCP. The acceptance criteria emit through a small test plugin that any vitest or jest suite can pick up in a single import. The scaffold that drives the loop is open source. We have been building it with itself for the better part of a year, which is how I know the morning-of-the-spec rhythm is real and the bookend genuinely closes. The thing I would want a reader to take from this piece is not the product but the shape. The shape will be the shape whether you reach for our harness or someone else’s or build your own.

What survives, what changes

Tickets survive. Linear, Jira, whatever you reach for: those are the pre-spec layer, the place ideas live before they are ready to be specified. The rituals from Chapter 5 (standups, retros, the planning conversations) survive too. The artefact at the centre of the team’s work changes, and quite a few rituals reshape themselves around it, but the rituals that were about humans coordinating with each other do not go anywhere.

The thing that genuinely changes, and the thing this chapter is really about, is the pace a team can sustainably hold. Three to five specs per human per day is the cadence I have watched our own team settle into, and that volume is unsustainable on any older shape of the artefact. A Word-document spec at that pace collapses inside a fortnight, and a Linear-ticket spec collapses sooner. The database does not, because it absorbs the work the engineer used to do by hand: decisions stay current, acceptance criteria stay current, the build phase has somewhere to put its issues, and the verify phase has somewhere to read its outcomes from. The engineer stops hand-stitching the artefact and starts directing the work that happens around it.

That is the move worth being honest about. It is not that any one feature gets built faster, though most do. It is that the rate of meaningful work a team can sustain has lifted by something larger than I have a clean number for, and a team trying to run at that rate on a document instead of a database will burn itself out before the quarter ends.

Specify, build, verify: the middle is the easy part now, and the work has moved to the brackets. The brackets, when they are doing their job, are a database.

Barrie