Onboarding engineers into a codebase your agents wrote

You onboard someone into an agent-written codebase by giving them the decisions behind it in merge order, over a map of the system, instead of a person to ask. An agent explains the code on demand; it cannot say which alternatives were rejected or what was assumed. Backthread keeps that record from every merged change's agent sessions and pull-request threads, and shows how the system works per area, with how much the team understands.

Why is onboarding to an AI-generated codebase different?

Nearly every article that ranks for this question is about the inverse problem: using an AI assistant to get up to speed on a codebase humans wrote. Birgitta Böckeler's piece on martinfowler.com (August 2024) is the careful version of that genre; the dozens of "two weeks to thirty seconds" posts are the careless one. They share an assumption that no longer holds for teams shipping with Claude Code, Cursor or Codex: that somewhere behind every module there is a person who read it as they wrote it, and that the AI is a faster path to what that person knows.

In a codebase where the agents did the writing, the person on the commit pressed merge. They may have skimmed the session. They may have read the diff. They did not necessarily form a model of the change, and a new hire who "asks the author" gets a shrug or, worse, a confident answer reconstructed on the spot. We measured the size of this on our own repository: of 4,302 decisions our extractor recovered from agent sessions, 1,613 carried an alternative or a trade-off; the rest were made without one. The reasoning the new engineer wants was, for most changes, never held by anyone. That is the number to keep in mind when someone says onboarding is a documentation problem.

The second difference is volume. A team shipping with agents merges in a quarter what it used to merge in a year, so the codebase a new hire walks into is younger, larger and less settled than its age suggests. The dev.to piece "Onboarding engineers in an era of code explosion" (May 2025) names the problem and then sells a search box. Search finds where. Onboarding is about why.

What can the new hire actually get, and from what?

It helps to be precise about the three kinds of knowledge a new engineer needs, because the tools cover them very unevenly.

The first row is solved. DeepWiki, CodeTours, a /explain in the editor, or the coding agent itself will narrate any file. The May 2026 guide at super-productivity.com puts the limit well: "AI can describe what each module does. It cannot reliably tell you where the boundaries are and why without supporting architecture context." Top-down understanding, the same article says, "depends on context outside the code: product goals, design history, domain constraints, ADRs, and teammate knowledge." In an agent-written codebase the ADRs were never written and the teammate knowledge is thinner than the commit log implies.

The third row is the one that decides whether the new hire is productive in week three or still making the mistakes the last three pull requests already made. It cannot be regenerated after the fact. It can only be captured while the work happens, from the session where the agent weighed options and from the pull-request thread where someone objected. That is what Backthread does, and it holds each decision until its work merges so the record is of what shipped rather than what was tried. The alternatives and trade-offs it shows are only the ones that were actually voiced; when a change carried none, it says so rather than inventing a rationale.

How do you run onboarding without an author to ask?

The substitute for "ask the author" is a reading order. Here is the one we use, and it works with a spreadsheet before it works with any tool.

1. Start from the map, not the README. The README describes the system someone intended to build. A how-it-works view built from the actual repository shows the one that exists, with its subsystems and the edges between them. Give the new engineer the map first and the README second, so they read the README as a claim to check.
2. Read the decisions of one area in merge order. Pick the area they will work in first. Read its decisions oldest to newest: what was chosen, what was rejected, what was accepted as a cost. A decision that says "we chose X over Y because Z" teaches more in forty words than an hour of stepping through the code, because it tells the reader what not to try. This replaces the "sit with the senior engineer for an afternoon" session that no longer has a senior engineer who holds the area.
3. Ask the recorded history, not the model's memory. When the new hire hits a "why is this like this?" they should ask a query that answers from the recorded decisions with citations (/backthread:how inside the coding agent) rather than a chat that reconstructs a plausible rationale from the code. A confident invented reason is the worst outcome of onboarding, because it gets repeated. The same guide warns that an unverified architecture summary "is worse than no summary at all" once it is committed and read as ground truth.
4. Look at the coverage before assigning the first task. Every area of the map carries a knowledge-coverage figure: how much of it the team can explain. The first picture is inferred from git and pull-request history, capped at 50% and labelled an estimate, because having touched an area is not understanding it; above that, coverage is earned by explaining decisions. Put the new hire's first task in an area where at least one person genuinely holds the model, so there is someone to check their reading. Areas showing "nothing on record here" are for month two.
5. Let the teaching happen in the flow. After the first week, the new engineer learns the rest of the system the way they touch it: when their agent is about to change an area, the decisions behind that area are shown while the agent is thinking, or on demand. Not a session on the calendar, and not a quiz app; the reasoning arrives next to the code it explains.

The lesson from step three carries the whole method: in an agent-written codebase, the risk is not that the new hire finds nothing. It is that they find an explanation, and it was generated a second ago.

What do the existing onboarding tools cover?

They are good tools for the first two rows of the table above, and worth knowing about.

• CodeTour (the open-source VS Code extension) plays back hand-recorded walkthroughs. Someone has to record them, and in a codebase that turns over every fortnight they go stale within a month.
• CodeTours (codetours.ai) reads a repository and produces "8–15 steps covering architecture, entry points, build, run, and extension points". Generated from the code; nothing about why.
• OnBoardAI (onboard-developer.com) scans a repository into a structured plan with first tasks and a manager view, from $29 a month for two repositories and two users. Also code-derived; the "risks" it lists are structural, not decisions someone made.
• DeepWiki and the auto-generated-wiki family explain the code as it is, free for public repositories. We compare the alternatives in DeepWiki alternatives for understanding your own codebase.
• CodeSee, which many teams used for exactly this (maps and onboarding tours), was acquired in 2024 and its site no longer resolves; what covers each of its uses now is its own page.

None of these record a decision at the time it was made, and none tell the leader whether the new hire, three weeks in, actually holds the area they were given. That is the gap, and the reason we wrote why most agent-written code has no why: the reasoning is not lost in these codebases. It never formed, and the only fix is to catch the part that does form, at merge.

What does the engineering leader see?

Onboarding is usually judged by feel: the new hire seems fine, they shipped something, nobody complained. Under agents that signal is empty, because an engineer with a coding agent can ship into an area they do not understand from day two. What the leader can see instead is the coverage of the area the new hire was assigned, before and after: whether the number moved because someone explained the decisions, or whether it stayed at the inferred estimate. That is the difference between a person who has been onboarded and a person who has been given commit access. For a longer treatment of that distinction, see who on your team understands each part of the codebase.

Pricing is per seat, which suits this use: the new engineer is a seat on the fourteen-day trial before they are a line on the invoice. It is $25 per seat per month after that, one repository included and $10 for each further one, with the reasoning captured before anything leaves the machine and source never stored (security).

Connect one repo and the first map and the inferred coverage estimate are there before the next hire starts; the decision record fills from the next merge onward, so it is worth connecting before you need it. The trial is fourteen days with everything on, and if your codebase was written by hand and its authors are still in the building, you probably do not need this yet.