What an acceptance spec is, and why your agent needs one

It does not, unless you give it something to check. An acceptance spec is a file per feature that states what must be true — the table exists, the service is covered, the route answers, the plan limit is enforced — and runs against a real database and a real running server. The agent runs it until it is green, so finishing is a fact rather than a claim.

Coding agents are good at writing a feature and bad at knowing when they are done. Ask for "workspaces with a per-plan limit" and you will get a route, a table and a component — all plausible, none of it proof. Did the migration run? Does the limit actually refuse the fourth workspace? Nothing in the transcript tells you, so you read every line, and the agent has saved you typing at the cost of your attention.

A definition of done a machine can check

Every slice in this kit carries an accept.ts. It is not a test file in the usual sense — it is a contract, written before the code, in terms of what the feature must do rather than how it does it:

export default acceptance("workspaces", {
  migration: { table: "workspaces", columns: ["id", "user_id", "name"] },
  service: { fn: "createWorkspace", test: "src/features/workspaces/workspaces.test.ts" },
  route: { path: "/dashboard/workspaces", authed: true, status: 200 },
  entitlement: { plan: "free", limit: "workspaces.max", overLimitStatus: 402 },
  e2e: "e2e/workspaces.spec.ts",
});

Then pnpm accept workspaces boots a real server, migrates a real database, and checks each clause. Green is not an opinion.

Why it has to run against real things

A mocked database proves your mocks agree with each other. The clause that matters most here — the entitlement one — drives the service until the plan's ceiling is reached and asserts the next call is refused with a typed 402. You cannot fake that convincingly, because the interesting part is the interaction between the plan, the service and the row count.

The rule that keeps it honest

Never weaken a clause to turn a run green. If a run fails, the fix goes in the product, the generator, or the conventions — never in the spec. A spec that bends to the code it was meant to check is a spec that has stopped measuring anything.

That single rule is what makes an unattended run trustworthy. The agent can edit the feature freely; the one file it must not touch is the one that says whether it worked.

← All Posts