Point a coding agent at a SaaS boilerplate and ask for "premium plans with a
14-day trial". If the agent does not know that internal/billing exists,
what you get back is impressive, plausible — and wrong: a second Stripe
client, a second webhook route, a plans table that duplicates one already
served by configuration. Everything compiles. Half of it is untested. You
now own two billing systems.
This is not a hallucination problem in the usual sense. The agent did not
invent an API; it invented work. And it invented it because nothing told
it the work was already done.
The reflex is to prompt harder: "use the existing billing code". It helps
once. It does not survive the tenth session, the second agent, or the
teammate who forgot the incantation. Instructions that live in chat
history die with the chat.
What survives is a file in the repository that every agent reads before
writing — if, and only if, that file cannot rot.
GoVueKit ships AGENTS.md at the repository root — the file Codex, Cursor
and their kind read natively; CLAUDE.md imports it, so Claude Code reads
the same one. It is not prose about being careful. It is a table:
| capability | package | extend through |
|---|---|---|
| payments | internal/billing |
billing.Provider |
internal/email |
email.Mailer |
|
| files | internal/storage |
storage.Storage |
| background jobs | internal/jobs |
Queue.Register |
| signup side effects | internal/auth |
OnUserCreated |
| roles & tenancy | internal/http |
RequireOrgRole |
with one instruction above it: before writing anything, find it here.
"Premium plans" now resolves to configuration plus the existing provider seam, because the map says so in the place the agent looks.
The map also carries the rules the codebase enforces (portable SQL,
organization_id on every business query, webhooks idempotent, French and
English in step) and the chain a new feature follows — migration, queries,
domain package, handler, route, store, view, tests. An agent that knows
the chain produces a diff shaped like the codebase instead of a framework
of its own.
Documentation drifts; that is why agents ignore it. GoVueKit's map is held
by a test, cmd/server/agents_test.go, and the suite goes red when:
internal/ package exists that AGENTS.md does not mention — you
added code, you map it, or CI fails;billing.Provider cannot silently become something else.
The consequence is worth stating plainly: if make test is green, what
the map says is true. That is a property most documentation cannot claim,
and it is the property that makes an agent's trust in the file rational.
The map narrows what the agent writes; the suites judge it. 186 Go tests
run on both PostgreSQL and SQLite, 48 frontend tests include a check that
the French and English catalogues define exactly the same keys, and 14
Playwright journeys drive the real production binary — including the
cross-tenant request that must 404. An agent's diff that leaks tenant data
or forgets a translation fails before you read it.
For the final look, the labs boots the whole product locally — SSO,
uploads, checkout, email — from one file, with nothing to configure:
curl -fsSLO https://govuekit.dev/labs/docker-compose.yml
docker compose up -d
Three concessions, because a harness is not magic.
First, the map keeps an agent from rebuilding the foundation; it does not
make your feature idea good. An agent will faithfully implement a workflow
your users never asked for, tests green all the way.
Second, an agent can still write a worse version of something inside the
right file. The seams tell it where; they do not guarantee elegance.
Review stays your job — the harness only shrinks what needs reviewing.
Third, this works partly because the kit is small: 19 Go packages, a
schema in one migration file, an architecture that walks in ten minutes.
A map over a sprawling framework would be a book, and agents do not read
books. If you evaluate another starter for agent work, ask how much of it
fits in a context window — and whether anything fails the build when its
documentation lies.
Originally published on govuekit.dev. GoVueKit is a complete Go + Vue 3 SaaS codebase you buy once and own; the whole stack runs on your machine with one docker compose up: https://govuekit.dev/labs