AI Onboarding

Two new starts happen on the same Monday. One is a mid-level engineer, hired to join a team that adopted an AI coding agent eight months ago. The other is that same team’s agent, opening its first session on a service it has never touched — not because the service is new, but because this session has no memory of the four hundred sessions that came before it on this codebase. The human gets a laptop, a repo-access ticket, a Slack channel, a style guide, and a call with their manager. The agent gets whatever happens to be sitting in the repository’s root directory. Neither onboarding plan was built for the job each is about to do.

The human’s checklist was written for a world where the hardest new skill was the codebase itself — where to find things, who owns what, how deploys work. Nobody updated it to cover the skill this team now needs most: how to write a goal an agent can act on, how to review the diff that comes back, how to tell a change worth trusting from one worth re-deriving by hand. The agent’s checklist barely exists at all. If the team has a CLAUDE.md or an AGENTS.md file, the session inherits something. If not, it starts from exactly the same blank state as the agent that ran here yesterday, and the one that will run tomorrow, having learned nothing durable from either.

What the data says about ramping humans

The measurable evidence on the human side is more encouraging than the anecdote above suggests, with a sharp condition attached. DX’s Laura Tacho, analyzing engagement data from six multinational enterprises in September 2025, tracked time to a new hire’s tenth pull request — an established proxy for real ramp-up — and found daily AI users reaching it in a median 49 days against 91 days for engineers who never used AI tools, with weekly and monthly users landing in between at 73.5 and 84 days. That is a genuine, measured effect, and it argues against treating AI adoption as a distraction from onboarding rather than part of it.

The sharp condition is that the gain accrues to daily, competent use, not to mere access. Gergely Orosz and Elin Nilsson, surveying engineers in May 2026 for the Pragmatic Engineer newsletter, report a consistent theme from staff-level engineers: AI tools amplify the engineer driving them, meaning a junior engineer who has not yet learned to write a good goal or read a diff critically stays junior, only faster and with more output to show for it. One respondent put it plainly — companies need to give junior engineers room to grow and treat AI as a booster, not a replacement. The DX numbers and the Pragmatic Engineer warning describe one mechanism from opposite sides: ramp-up accelerates when directing AI is itself something the org actively teaches, and does nothing reliable when that skill is assumed to arrive on its own.

The skills the old checklist never covered

Name the actual skills, because a checklist that says "learn to use AI well" teaches nothing. This Library’s second volume opens by establishing that a prompt is one instruction competing for space in a much larger window, and its third volume’s first chapter goes further — a prompt is an interface, judged on whether it states scope, supplies a worked example, and gives a checkable definition of done, not on how politely it asks. A new engineer who has never had to think about a request that way arrives with none of that vocabulary, because nothing in a conventional CS program or bootcamp curriculum teaches it; the skill did not exist until agents that act on natural-language requests did. Tooling that scores a goal against those same structural criteria before a session starts — flagging a missing scope or an unstated success condition, rather than grading tone — gives a new hire something to calibrate against instead of a vague sense that some requests "just work better."

Reviewing what comes back is a second skill with no clean precedent in traditional onboarding, and it deserves more space than this chapter can give it — this volume’s own chapter on the new review culture takes up directly what changes when review runs at roughly twice the historical volume, functioning as gatekeeping and mentorship at once. What belongs here is narrower: a new engineer needs to be told, explicitly, that reading an AI-generated diff is not the same motion as reading a colleague’s, because the failure modes differ. Knowing when to read closely versus when to trust the output outright is its own separate judgment call — this Library’s verification volume names it trust calibration, and shows that trusting an unreliable step and re-deriving a reliable one from scratch are both well-documented failure modes with no shortcut but a track record actually checked against outcomes. A new hire absorbing that calibration by osmosis, the way engineers once absorbed "which parts of this codebase are scary," is exactly the mechanism behind the drift that chapter opens with — a habit nobody decided on, formed by a tool being right often enough to stop feeling interesting.

Nobody wrote "how to review a diff you didn’t write the logic for" into an onboarding doc, because five years ago that was every review. It stopped being every review, and the doc never noticed.

Onboarding a session that remembers nothing

Flip to the agent’s side, and the problem inverts completely. A new human hire arrives once and, from that point forward, accumulates context every day they stay — the codebase, the team, the incidents, the unwritten rules. A new AI session arrives, by design, with none of that, whether it is the agent’s first session on a project or its four-hundredth. Anthropic’s own engineering guidance is blunt about what this means: a model’s output is a function of what is actually present in its context window at generation time, and nothing persists into the next session unless something deliberately puts it there. An agent does not ramp up. It either starts from something better than zero, or it starts from zero, on a fixed schedule, forever.

What "something better than zero" actually means is the subject of this Library’s third volume, and it is worth naming precisely rather than gesturing at loosely: a standing intent file — a CLAUDE.md or AGENTS.md sitting at a project’s root, following the constitution pattern that volume’s fourth chapter names, layered by scope the way its eighth chapter describes, from an org-wide baseline down to a directory’s narrower conventions. The AGENTS.md specification builds exactly this into the format, having agents automatically read the nearest file in the directory tree so a session inherits the right layer of instruction without anyone re-explaining it turn by turn. That is a session’s entire onboarding checklist, and unlike a human’s, it has to be complete and current before the first tool call — there is no ramp period in which an incomplete understanding gets corrected through experience. There is only this session, working from whatever the file says, or does not.

It would be a mistake to read this as an argument that more intent-file content is automatically better onboarding — the evidence does not support that reading. A February 2026 benchmark by Thibaud Gloaguen and colleagues, evaluating AGENTS.md-style context files across real repositories and multiple coding agents, found files generated by an LLM — a common, cheap way to populate one — actually reduced task success on average while raising inference cost over 20%, largely because the generated content mostly repeated documentation a session could already discover on its own. Files written by a person did better, but only modestly, adding roughly four points of task success at a similar cost premium. The finding is genuinely contested rather than settled, and it cuts against the reflexive advice to "just generate one." A padded, low-signal file is not a small inefficiency for an agent the way it is for a human skimming past a boilerplate paragraph — it competes, token for token, with the two or three facts that would have actually mattered.

The asymmetry, stated plainly

The two halves of this chapter are not the same problem wearing different clothes. A human engineer’s onboarding investment compounds. Every month on a team builds tacit understanding — the sense of which part of a system is the genuinely hard problem, which change should feel routine and which should feel dangerous — that this Library’s ninth volume, in its chapter on engineering wisdom, traces back to Michael Polanyi’s foundational distinction between what a person can tell and what they merely know. That judgment was never fully written down for a human either, but a human carries it forward on their own, year to year, without anyone re-teaching it. An agent’s onboarding does not compound in that sense at all. Unless a team has built the durable, retrievable substrate that lets a new session start from something real — the layered intent files above, a decision graph a session can query for why a prior choice was made, documentation genuinely written with a machine reader in mind — every session is onboarding day one, no matter how many sessions came before it.

That gap is exactly why documentation now has two audiences competing for the same page, in something close to equal measure: a 30-day sample of roughly 790 million requests across Mintlify-hosted documentation sites put AI agent traffic at 45.3% of total requests in early 2026, nearly matching human browser traffic. This volume’s ninth-volume sibling chapter on engineering documentation already made the structural case for what that means — a doc has to serve a reader with no tacit context and no time to build any, alongside a reader who has both — and it is the identical fork this chapter’s two halves describe, applied to onboarding rather than documentation generally. A human absorbs an implied convention by noticing it holds everywhere else in the codebase. An agent needs the convention stated once, somewhere it is guaranteed to read before it acts — and if that somewhere does not exist, the convention effectively does not exist for any session that ever runs there.

Two onboarding problems, side by side

Read across that table and one line does most of the explanatory work: an agent onboarding well is not really a property of the agent. It is a proxy measurement for how good the team’s knowledge infrastructure already is — the argument this Library’s ninth volume closes on in its own capstone, that engineering knowledge only survives contact with a fast generation layer if it is treated as infrastructure rather than folklore, budgeted and owned the way a build pipeline is. A team whose new AI session gets productively oriented in minutes has already built that infrastructure, whether or not anyone framed it that way. A team whose every session starts confused has not, and no amount of prompting skill in the humans directing it will compensate for a project that never wrote its conventions down anywhere a session is guaranteed to read them.

The organizational practice this implies

Most engineering orgs already maintain a new-hire onboarding checklist with an owner, a review cadence, and someone accountable for keeping it current, because everyone accepts that a stale onboarding doc costs a new engineer weeks. Very few maintain the equivalent checklist for a new agent session — the intent files, the layered scope rules, the decision record a session should query — with anything like that seriousness, even though skipping it is the same category of loss, paid every session rather than once per hire. Both checklists answer a structurally identical question: how does someone, or something, with no history here get productive fast. A team that reviews one of those checklists quarterly and lets the other rot from the day it was generated has only solved half its onboarding problem, and probably does not know which half.