The one-hour test: getting a codebase ready for AI agents

Picture a new engineer. Extremely capable, knows nothing about your company, remembers nothing from yesterday, leaves in two hours and makes mistakes very fast. That's a fair description of an AI coding agent. So when a team asks us which model to use, we answer with a different question: what has to exist around that person for their work to be safe to ship?

We build products, and AI changed how we build them. We're agnostic about models and clouds. What matters is the scaffolding around them, and most of that scaffolding is stuff good engineering teams already knew they should have.

The one-hour test

Here's the test we use. Could you hand a piece of work to someone brilliant and have them learn everything they need in under an hour? If a new engineer needs three weeks to become useful, an agent never will.

The bottleneck is not the model. It is your documentation.

That's why the first thing we check in a codebase is the documentation, before any AI tooling. Do the specs, architecture decisions and product docs exist, and do they live next to the code, versioned with it?

Four layers around every agent

Everything we built for this falls into four layers.

Context: what the agent needs to know

Specs, architecture decisions and product documentation, versioned in the repository next to the code. Our own website's repository has an AGENTS.md file that every agent reads first. It explains how the site is built and records the mistakes we don't want repeated, each with the measurements behind it.

Harness: what it can't get wrong

Test coverage, linters and architecture rules that run on every change, whether or not anyone remembers to ask. More on this below, because it's the layer teams underestimate.

Containment: where it's allowed to work

A temporary, isolated environment with no route to the internet and no access to production secrets.

Evidence: how we know it worked

Automated checks of behavior, plus a record of who approved what and why.

The harness goes first

A harness is the set of automatic rules that stop a mistake from reaching production, even when the agent gets it wrong. For us that means test coverage nobody can waive, linters that fail the build, architecture rules enforced automatically and naming conventions strict enough to reject a bad function name.

How strict it gets depends on the project. A regulated system gets the hard version. An early prototype gets a lighter one so the team can move. Either way, the harness is the expensive part and it comes first.

Security belongs in the architecture

An agent with internet access and sensitive data in the same room is an incident waiting to happen. Asking the agent to behave doesn't fix that. The environment does: the agent reads the repository and writes a proposed change inside a sandbox, a person reviews that change, and the logs keep everything it did.

Two lanes: decide and execute

We split every piece of work into two lanes. People own the spec, meaning exactly what gets built. They own the approval, which is named, recorded and required. And they own the next call: what the feedback means and what happens after.

Agents execute the rest. They build in an isolated environment, write and run tests before the pull request, do a first review that catches the obvious, deploy through continuous integration and keep monitoring with logs and telemetry.

Nothing reaches production without a person approving it. Three of the eight steps belong to people, and no amount of speed anywhere else buys a way around them.

What speed looks like

On Dreamer, the AI-native operating system from /dev/agents, our team designed and built seven apps in three months. Ideas went from concept to working prototype in two or three days. Designers wrote code for their own work and developers made design decisions while building, with Claude Code, Figma Make and Sidekick as the infrastructure of the workflow rather than add-ons.

The speed came from collapsing the handoff between design and development. The people who moved fastest could hold both in their heads at once and still make the call on what was good enough to ship. The team's own line for it: vibecoding with speed is straightforward, vibecoding with pixel-perfect thinking is something else.

Where agents still fall short

These are the parts we'd rather not put on a slide:

• Some work is still faster by hand. Small, gnarly changes in code with a lot of history often cost more to explain than to make.
• The harness is expensive before it pays anything back.
• Stale documentation degrades everything quietly. When the docs and the code disagree, the agent believes the docs and confidently builds the wrong thing. That's why we review documentation on a schedule, and nobody gets to skip it.

Where to start

If you're getting a team ready for agents, start with the one-hour test. Take a real task, hand it with your docs to someone new and time how long it takes them to be useful. Whatever slowed them down is your first backlog: missing specs, knowledge that lives in one person's head, tests that don't exist yet.

None of this replaced our engineering process. It made it mandatory. Documentation, tests, continuous integration and recorded decisions used to be good habits. Now an agent can't work without them. There's a shorter version of all this on our AI page.