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.
The five layers
| Layer | What the agent can run alone | What it cannot prove |
|---|---|---|
| View on fixtures | every state of every screen, in the real frame | that real data looks like the fixture |
| Rules as functions | inputs and outputs, in milliseconds | that anything calls them |
| Vendors behind a seam | the whole app with no keys | that the vendor behaves like the fake |
| Data on a real database | migrations, constraints, races | production's data shape |
| Glue, end to end | the observable side effect | anything 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:
- A test must go red on the code it claims to catch. If it is green before the fix, the test is wrong, not the code.
- Assert the invariant, not the message. The loser's error text varies with the interleaving. Exactly one winner does not.
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:
- A local harness for real prompts. The agent runs product prompts end to end on its own machine, writing to a local database, with short-lived tokens it mints itself.
- Real read-only data where emptiness lies. The local search database had zero rows, so every "no results" check against it was meaningless. The harness reads search data from a read-only production replica and writes nowhere but local.
- A sign-in that needs no inbox. When the magic-link email cannot be delivered locally, the agent redeems the stored token directly and gets a real signed-in browser session.
Making your own code reachable
- Split every screen into a data layer and a props-only view, and give the view fixtures for typical, empty, loading, error and worst case. Register them somewhere the app can render them with no login.
- Pull decisions into pure functions and test them with real inputs. Delete tests that restate the code.
- Put each vendor in one directory with a no-op default and a check that enforces the boundary. Keep the interface as wide as today's use.
- Test data code on a real database, and prove every test can go red.
- Give the agent a way to run the real thing: a local harness, read-only real data where an empty database would lie, and a sign-in it can complete alone.
- Say which layer verified a fix. "Unit-green" and "works end to end" are different reports.
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.