Onboarding onto a codebase nobody wrote

Somebody hands you a codebase and a date, and the one thing they can’t hand you is the person who wrote it.

That’s true of most inherited projects, and it’s true in a particular way of a prototype built with AI. There is an author, in the sense that someone sat there and ran the prompts. The gap is that nobody read the result closely enough to tell you which parts are load-bearing and which are leftovers from an approach that got abandoned on a Tuesday and still look finished from the front.

Normal onboarding is a transfer between people. You get a walkthrough, you ask the dumb questions early, and somebody says “don’t touch that; there’s a reason.” On an inherited prototype, that conversation has very little to draw on, and the code is the only surviving record of decisions nobody made deliberately.

There’s a number for what reading costs, and it comes from long before any of this. A field study tracked 79 professional developers over two weeks, 3,244 working hours in total, and found they spent around 58% of that time on program comprehension – reading code and working out what it does, rather than changing it. That was measured on codebases people had written by hand, with the authors still sitting nearby (Xia et al.). Take the authors away and hand the reader something assembled at speed, and I doubt that number goes down.

So before anyone writes a line, we generate a map.

It’s a skill we wrote ourselves, for the reasons in the last article, and it produces one file: docs/ATLAS.md. The agent walks the repository and writes out what’s actually there.

Every route in the application goes in, with the file that implements it and a sentence on what it’s for. Every API endpoint gets the same treatment. Then there’s a feature inventory as a table: which surfaces a capability appears on, what data it owns, what it depends on, what it’s meant to do, and its status. The three to five most important user journeys are drawn as sequence diagrams, with the real file names in the participant labels, so you can go from the diagram to the code without searching. There’s one entry per screen. And at the end there are pointers to whatever architectural decisions have been recorded, plus a note on the one or two load-bearing decisions that clearly exist but were never written down.

Most of that is inventory. The status column is the one that changes how people work with the file.

The scope stops there on purpose. The atlas is the building directory in the lobby. The specification, the data contracts, and the architecture decision records are the floor plans, and they stay separate documents. The atlas tells you what’s in here and which door to open.

The feature inventory has a status on every row: shipped, prototype or mocked, planned, not started.

Filling that column in on a demo is the uncomfortable part, and it’s why the document earns its place. A prototype is built to be shown, so it’s full of things that look complete from the front. The inventory makes somebody write down, per feature, whether the thing behind the screen is real. The everyday use is cheap: there’s a line in the skill telling you to grep that table before adding anything, because a conflict found there costs less than one found after the code is written.

The first pass is where you learn the most about what you’ve been handed. What tends to turn up is a route returning hardcoded data dressed as a live endpoint, or a screen wired to a stub service that nobody relabeled once the demo was over.

A practical example is user journeys, which, although they sometimes use Mermaid diagrams, turn out to be incomplete. The diagram showed specific steps, start to end, but inspecting it more deeply, with our atlas, showed that there were missing steps. To be clear, we didn’t trust it initially. The first few times, we had our QA team going through the journeys to validate that the atlas produced reliable outcomes.

It’s hard to measure exactly how much time it saves for onboarding. But a good comparison, any developer would understand, is to get familiar with a complex codebase without no documentation or code comments at all, versus a very well-documented project.

The atlas is written for whoever needs orientation, and on our projects that’s two kinds of readers.

A person joining the team reads it on day one and can skip most of the archaeology. An agent picking up a ticket reads it for the same reason, and gets the answer to the question that causes most of the damage: does this already exist somewhere? A model that can’t see the whole repository will build you a second version of a thing you already have, confidently, and it will pass review if the reviewer doesn’t know either. It’s how two people in the same flat both come home with milk. The atlas is one of the cheaper ways to make that less likely, and it works because the agent reads the same material the humans read.

The failure mode is obvious once you’ve seen one go stale. An atlas that nobody updates gives you a false sense of where things stand, in the same quiet way a green test suite that asserts nothing does: everything looks fine until someone acts on it.

So the update rules live inside the file. A pull request that adds a feature adds a row to the inventory. One that changes a journey updates the diagram. If a route is added, removed, or renamed, both the route list and the diagram it appears in have to move with it. And if a reviewer sees code that contradicts the atlas and the atlas hasn’t been touched, that’s a rejection, the same as any other missing piece of work.

We can also regenerate it, and we do. A regenerated atlas tells you what the code says. What the team meant still has to come from people who know why, which is the intent column and the status column.

The instinct on day one is to produce a plan, but the map comes first. It’s a boring document; it takes less time than the arguments it prevents, and it’s usually the first place where you can see what the code actually is instead of what the demo made it look like.

If you’re staring at a prototype somebody else built and wondering where to start, that’s where our Production Readiness Review begins – ping us.