Building with a coding agent

The kit assumes you may not type every line yourself. Claude Code, Codex, Cursor — whichever agent you point at the repository, the same two files keep it on rails.

The failure mode this prevents

Agents fail on boilerplates in one specific way: they rebuild what already exists. Asked for "premium plans", an agent that does not know internal/billing writes a second Stripe client and a second webhook route — and now you have two, one of them untested. The fix is not a smarter prompt; it is a map the agent cannot miss.

AGENTS.md — the map

AGENTS.md at the repository root is that map, in the file coding agents read natively (CLAUDE.md imports it, so Claude Code reads the same one). It carries:

• the capability table — every feature, its package, and the seam to extend it: payments → billing.Provider, email → email.Mailer, files → storage.Storage, jobs → Queue.Register, signup side effects → OnUserCreated, roles → RequireOrgRole, outbound HTTP → safehttp.NewClient;
• the rules the codebase enforces — portable SQL, organization_id plus 404 on every business query, webhooks idempotent, FR and EN in step, the unconfigured path tested;
• the feature chain — migration → queries → domain package → handler → route → store → view → tests, one obvious file per layer;
• the commands and what "done" means.

The map cannot drift

cmd/server/agents_test.go fails the suite when:

• an internal/ package exists that AGENTS.md does not mention;
• AGENTS.md references a path that no longer exists;
• a named seam is renamed — the seams are compile-time references.

So the map is as trustworthy as the tests: if make test is green, what AGENTS.md says is true.

A workflow that works

1. Ask for the feature in product terms ("members can archive a project"), not in implementation terms. The agent finds the chain in AGENTS.md.
2. Let the suite arbitrate: make test, make test-front, make e2e. The kit's tests catch cross-tenant leaks, missing i18n keys and broken webhooks before you read a diff.
3. Verify by hand in the labs — the full stack, locally, nothing to configure.

When you add your own packages

Add a row to AGENTS.md for every internal/ package you create — the conformance test forces it. That discipline is for your own future agents: six months from now, the map still tells them what not to rebuild, including the parts you wrote.