Last week an AI agent built two complete admin surfaces in my platform — a live operator console for our data lake and its workspace-owner twin. Nineteen thousand lines across two overnight runs. Reviewed, tested, merged, running in production repos by the weekend.
Here’s the part that makes it an experiment instead of an anecdote: the agent never had the manual.
By accident, the whole thing ran from the wrong repository — a scratch pile of uploaded CSVs and log dumps that happens to share my machine. My platform ships with a project instruction file, the thing every AI coding setup treats as sacred: load it into context, and the agent knows the house rules. This agent never had it loaded. Not once. By every convention of AI-assisted development, it worked blind for three days.
It succeeded anyway, and the reason is worth more than the feature it shipped.
Discovery Beats Preloading
The agent did something simpler than being instructed. It read.
Before touching the lake, it read the lake package’s own doctrine file — 388 lines of contract, lifecycle, and invariants. Before building the admin page, it read the admin shell’s documented swap contract and the design doctrine. Before every phase, a planning pass verified each integration point against the actual code, file and line, and every claim in its reports got checked against the source before a commit happened.
The instructions weren’t absent. They were discovered instead of preloaded — pulled at the point of need, from the same files a human would read. Which reframes what those files are: a preloaded instruction is a cache. The repository is the source of truth. This agent just had a cold cache and kept hitting the source, and the source answered.
Every question had a written answer within two hops. That is not a property of the agent. That is a property of the codebase.
The Experiment Was Never About the Agent
I’ve spent four months writing conventions down. Every non-trivial package carries its own explanation — key files, patterns, the bugs already paid for. Boundary rules are stated in words, then enforced in tests. The design documents record outcomes and the argument that produced them.
I thought I was doing documentation discipline. The experiment says I was doing something else: building a codebase that can be inhabited by a stranger. An agent parachuting into a typical enterprise codebase without instructions drowns — not for lack of intelligence, but because the knowledge lives in heads, and the heads went home. In mine, the knowledge lives in the repo, so any reader — human, machine, this year’s model or next year’s — can walk in cold and find the load-bearing walls labeled.
There’s a pleasing recursion here. My platform’s entire pitch is that the system explains itself — the lake console literally renders the record’s own invariants so a customer can watch correctness instead of being told about it. It turns out I’d been applying the same doctrine to the codebase all along. The repo is to the agent what the console is to the customer.
The One Failure
Honesty requires the failure, and the failure is instructive because of what kind it was.
Mid-build, the agent copied test data into my working tree — through a symlink it didn’t know I’d created an hour earlier, straight into my real estate. Nested directories in production data. It noticed, verified byte-by-byte which directories were the accident, removed exactly those, and confessed in detail.
Note what the failure wasn’t: it wasn’t a knowledge failure. No document could have prevented it — the world had changed under the agent’s feet and it acted on stale state. The failure mode of the uninstructed agent isn’t ignorance of doctrine. It’s the same one humans have: insufficient paranoia about what changed since you last looked. The fix isn’t more instructions. It’s the habit of re-checking — which, to its credit, is also how the mistake was caught.
The Verification Tax Is the Insurance Premium
One more honest caveat before the takeaway. The experiment worked uninstructed, not unverified. Every phase was reviewed against the code by a second pass before anything was committed; claims were re-tested; a boundary was checked to be untouched across the entire diff. Uninstructed-and-unverified would be a different article, probably titled with a postmortem number.
The formula that worked has three terms, and all three are load-bearing: a legible codebase, an agent that reads before acting, and a review gate that trusts nothing. Remove any one and the other two don’t save you.
The Wrong Question
Everyone I talk to about AI-assisted development asks the same question: how do I write better prompts for my agents? What should go in the instruction file?
After this week I think it’s the wrong question, or at least the smaller one. The instruction file is a cache, and caches go stale, and every hour spent perfecting one is an hour not spent on the thing that actually scaled: a codebase that answers questions.
Write the boundary down where the boundary lives. Put the package’s story in the package. Record the bug you just paid for next to the code that had it. Make the tests state the taste, not just the behavior. Do it for a few months and then watch a cold agent — wrong repo, no manual, no memory of your project — build something you’d been imagining for weeks, overnight, correctly.
The manual is the codebase. It always was. The agents just made it legible how much that matters.
There’s an encyclopedia where software principles get the roast they deserve, and a mythology where these ideas have been arguing with each other for a hundred episodes.
See also:
- Twenty Words — What the same week proved about delegation and the veto
- Why Every AI-Assisted Codebase Will Collapse (Unless Someone Loves It) — Why the writing-down happens at all
- Gall’s Law Got Cheap — Working systems, assembled from working systems