Writing

Build in layers so the agent can test without you

A coding agent can only test what it can reach without a person. No login, no keys, no production data. The five layers we build in so each one is a place the agent can run something real, what each layer can and cannot prove, and the false greens that taught us.

A coding agent tests what it can reach on its own. If checking a screen needs a signed-in account, an API key, a seeded database and a person to look, the agent will not check it. It will run the unit tests it can run, report green, and the gap will be found by a user.

So "agent-ready code" turned out to mean something concrete for us: code split into layers, where every boundary is a place the agent can run something real without asking anyone. The rule, in the owner's words, is that every screen and component should render with dummy data, built in layers so each can be tested on its own. This post is what that rule became across the stack, and where each layer stops being able to tell you the truth.

219 of 227
Page routes split from their data, one app
each page reads data; a sibling screen only renders props
5
States every screen fixture covers
typical, empty, loading, error, worst case
5 of 5
Runs a broken race test passed
until the connection pool was warmed first
0
Rows in the local search database
so every local 'no results' check meant nothing

The five layers

LayerWhat the agent can run aloneWhat it cannot prove
View on fixturesevery state of every screen, in the real framethat real data looks like the fixture
Rules as functionsinputs and outputs, in millisecondsthat anything calls them
Vendors behind a seamthe whole app with no keysthat the vendor behaves like the fake
Data on a real databasemigrations, constraints, racesproduction's data shape
Glue, end to endthe observable side effectanything faster than a real run

Each row exists because the row below it is too slow or too expensive to be the only test, and each row's right-hand column is where the next row has to take over.

Layer one: the view takes props and nothing else

Every screen is three layers. A data layer reads the session, calls loaders and server actions, and maps the result to props. A presentational view takes plain typed props and renders. Shared primitives sit underneath. A presentational component never fetches.

That split is what lets an agent open any state of any screen. Each view has a fixture file covering five cases: the typical one, empty, loading, error, and the worst case, the longest name and the list of two hundred. The fixtures are registered in a gallery the app can render inside its real frame, with no backend and no login. I wrote about the build order this enables separately. For testing, the point is narrower: the agent can now look at the empty state before a user finds it, and a sweep can walk every screen and every fixture with deterministic probes for overflow and clipped text.

The split also had to survive a design-system migration that moved every app onto one component kit. The rule held because it was about where data enters, not about which components draw it.

Layer two: rules are functions with real inputs

Logic that decides something, a price, a permission, whether a match is a brand or an English word, lives in a pure function. The agent tests it with real inputs and real expected outputs, in milliseconds, with no setup.

Two rules keep this layer honest. Tests must catch a change someone would regret: a money, security or data invariant, a rule with real inputs, a bug that actually happened. A test that restates the code, a snapshot of a config or an exact list mirrored from a registry, fails on every legitimate change and catches nothing. And dependencies are passed in, not mocked by swapping modules at import time. A function that takes its database pool or its clock as a parameter can be tested with a fake one, and an agent can see that from the signature.

Layer three: every vendor behind a seam

Each external service lives in one directory behind an interface that names no vendor. Its environment keys are read only there. It has a no-op or fixture default. A boundary check lists the directories allowed to import each vendor, so a stray import fails the build rather than waiting for review.

The testing payoff is that the agent can run the whole application with no keys at all. The original reason was different: an observability vendor was being replaced, and the owner wanted the swap to be one directory, one dependency and one set of keys, not a codebase-wide edit. Then the obvious generalisation, every third-party dependency that way, and the immediate caveat: do not overengineer.

So the seam has limits written down. The interface is exactly as wide as today's use: no registry, no injection container, no generic provider framework. A layer earns its place only when it costs less to read and maintain than the swap would cost without it, so a vendor referenced from one file is already its own layer. Frameworks the code is written in are not vendors. And we do not build portable abstractions over several vendors at once; that makes you the third platform.

Layer four: a real database, and tests that can go red

Queries, migrations and constraints are tested against a real Postgres on the machine, not a mock. A mocked database tells you the code called the mock the way the code calls the mock.

The false green that taught us the most was a race. A test fired two competing writes with Promise.all and asserted exactly one winner. It passed five runs out of five, on code that was broken. The driver opens connections lazily, so on a cold pool the second caller waited for the first connection and the two writes ran one after the other. There was no race to lose. Warming the pool first, opening a few connections before the competing calls, made the race real, and both callers won the same row.

Two rules came out of it, and they apply well beyond databases:

Layer five: glue, where green lies

The seam between your code and a framework is where unit tests stop telling the truth, and it is the layer an agent most wants to skip.

One fix for a cancelled stream had a passing unit test and a clean type check. The test called the function with the cancelled flag set directly. Live, the flag was never set, because the code drained the wrong branch of the framework's stream. Only a real server, a real session and a real mid-stream disconnect showed it. A rendering bug went the same way twice: fixed on unit tests, then broken again after a reload, because the rows persisted for the reload were ids with no bodies. "It works in the chat" and "it works after a reload" are different claims, and only querying the stored row tells them apart.

So for anything that crosses a framework boundary, streaming, callbacks, sessions, persistence, the agent verifies the observable side effect: the stored row, the emitted event, the billed cost. When something is unit-verified but not run end to end, it says so instead of saying fixed.

This layer needs reach too, or the agent cannot do it. Three things gave it that:

Making your own code reachable

None of these layers is new. What is new is who runs them. If you have found a layer your agent could not reach, and what it took to open it up, I would like to hear it.