Onboarding a Developer to an AI-Written Codebase

Onboarding a developer to an AI-written codebase is not the same job as onboarding them to a normal one, and the difference is not code quality. It is that the context which usually lives in people's heads never entered anyone's head. Nobody on the team remembers why the retry logic sits in the client rather than the service, because nobody decided it. An agent did, in a conversation that scrolled past three weeks ago.

Standard onboarding advice assumes tribal knowledge exists somewhere and the job is transferring it. Here it mostly does not exist. Your job is to reconstruct enough of it that the new developer can make safe changes, and to be honest about the parts you cannot reconstruct.

The three artefacts that carry the missing context

In a human-written codebase, the reasoning is distributed across the people who wrote it. In an agent-written one, whatever reasoning survives is in three places, and their quality varies enormously between teams.

The agent instructions file. If the repository has an AGENTS.md or equivalent, it is the closest thing to an architecture document, because it is the constraints someone actually cared enough to write down. It tends to be more accurate than a README, since a wrong README embarrasses you and a wrong instructions file breaks builds. Have the new developer read it first, before the code. If your repository does not have one, writing an AGENTS.md file is the highest-leverage thing you can do for the next hire.

The pull request history. Agent-generated PRs frequently include the task description that produced them, which is the intent behind the change stated in plain language. That is better documentation than most teams write deliberately. Six months of PR titles and descriptions read in order is a surprisingly good architecture tour.

The test suite, read as a specification. In an agent-written codebase the tests often encode the requirements more faithfully than any document, because the requirements were expressed as acceptance criteria and then turned into tests. Read the tests to learn what the system is supposed to do.

Notice what is missing from that list: the code comments. Agent-written comments describe what the line does, not why the approach was chosen, and reading them for design intent is a waste of a morning.

A first week that works

Day one: read, do not write

Give them the instructions file, then a written map of the system in your own words, half a page, however rough. The map matters because the codebase's own structure may reflect no deliberate decision at all, and a new developer will otherwise spend two days inferring an architecture that was never intended.

Be explicit about which parts were agent-written and which were hand-written and reviewed. This is not an admission of anything. It is calibration, and without it they will over-trust the wrong code.

Day two: make one small change with the agent, and one without

Two exercises, deliberately paired.

First, have them fix a small bug using the same agent workflow the team uses. This teaches the workflow, and it shows them what the team's review bar actually is faster than any document.

Second, have them fix a different small bug by hand. This one matters more. It forces them to actually read the code rather than delegating comprehension, and it surfaces the parts of the codebase that are hard for a human to follow. Those parts are where your future incidents live.

Day three and four: trace one request end to end, manually

Pick the most important path through the system and have them follow it by hand, from entry point to database and back, writing down every file it touches. No agent assistance.

This is the single most valuable exercise, and it is where the peculiarities of agent-written code become visible: the same validation implemented three times in slightly different ways, an abstraction introduced for one caller, a helper that duplicates something in the standard library. None of that is visible from a file tree, and all of it is important for anyone about to make changes. If the codebase resists this exercise, getting an agent to explain a legacy codebase is a reasonable fallback, though a supplement rather than a substitute.

Day five: have them write down what they found confusing

Not a retrospective. A list. The specific things that made no sense.

This list is the most valuable artefact of the whole week and it has a short shelf life, because in three weeks they will have internalised the oddities and stopped seeing them. Capture it while the confusion is fresh, then fix the top three items. Every subsequent hire benefits.

What to tell them explicitly

Four things that are true of most agent-built codebases and that a new developer will otherwise learn the slow way:

• Consistency is local, not global. Two modules built in different sessions may solve the same problem differently. Neither is wrong; they were written by different runs with different context.

• The git history is not a reasoning trail. Commit messages may be accurate and still tell you nothing about why. The PR description is the better source.

• Some code has never been read by a human. Say which parts, if you know. If you do not know, say that too. It is the honest answer and it tells them where to be careful.

• The review standard is the standard. Whatever your team's bar is for reviewing AI-generated code before shipping, it applies to them from their first PR, and it applies equally to code they wrote themselves.

The documentation gap, and a realistic fix

You are going to be tempted to generate documentation for the codebase with an agent. This partly works and it is worth knowing where the line is.

It works for describing what the code currently does: module summaries, API surfaces, data flow. It does not work for why, because the reasoning is not in the code to be recovered. Generated documentation that confidently explains a design decision the agent is inferring is worse than no documentation, since the new developer will believe it.

The workable compromise: generate the descriptive layer, write the decisions layer by hand, and keep them in separate files so nobody confuses one for the other. Even a short list of "decisions we actually made on purpose" is worth more than pages of inferred rationale. The mechanics of the descriptive half are covered in using AI to write documentation.

If you are handing the codebase over entirely

Onboarding a team member and handing a project off to an outside developer are different problems with different levels of context transfer. If nobody from the original build will be around to answer questions, the bar is considerably higher, and handing off an AI-built app to a developer covers what to prepare. The wider toolkit sits under AI coding tools.

FAQ

How long should onboarding take for an AI-written codebase?

Roughly the same as a comparable hand-written one, though the time is distributed differently. Less time reading code, more time reconstructing intent. Plan for a full week before expecting independent work.

Should the new developer use the same AI tooling from day one?

Yes for the workflow, no for comprehension. Learning the team's agent workflow early is efficient. Using it to avoid reading the code produces someone who can ship changes without understanding what they are changing.

What if the codebase has no tests?

Then you have lost the specification layer, and onboarding takes noticeably longer. Have the new developer write characterisation tests on the path they trace in days three and four. It teaches the system and leaves something behind.

Is agent-written code harder to onboard to?

Not inherently. It is usually more consistent in style and less consistent in approach than human code, and it carries far less recoverable intent. The style consistency helps; the missing intent is the real cost.