The Onboarding Playbook for an Agent-Heavy Codebase

TL;DR: Every onboarding template on the internet assumes the codebase a new hire is reading was written by humans, at human pace, with human-shaped mistakes. That assumption is already wrong at a lot of shops. When a third to three-quarters of new code is agent-authored, onboarding isn’t “the same 30-60-90 template, plus a CLAUDE.md link.” The actual skill a newcomer has to build is different: reading a diff without knowing who wrote it, learning which conventions are enforced by a linter-adjacent agent versus held only in a senior’s head, and figuring out what a mentor is even for when the boilerplate writes itself. This is the process for that, week by week.

The inversion nobody’s writing about

Search “onboarding new engineer AI” and you get two genres. The first is generic 30-60-90 templates that would’ve been fine in 2019 — same milestones, same checklists, with “review our AI tools” bolted onto week one like a compliance module. The second is “use AI to onboard your new hires faster,” which is a real and useful topic but the wrong direction entirely: it’s about deploying an agent to help onboard a human, not about what changes for the human when the codebase itself is agent-heavy.

Nobody’s covering the inversion, and it’s the harder problem. Your new hire isn’t reading a system that a team of people wrote over three years. They’re reading a system where a meaningful share of the commits were generated by an agent, reviewed by a human who was moving fast, and merged under time pressure that predates the new hire’s start date by exactly zero days. That’s a different codebase to onboard into, and it needs a different process — not a paragraph appended to the old one.

The scale of this isn’t hypothetical anymore. Google’s CEO said in April 2026 that 75% of the company’s new code is now AI-generated and approved by engineers, up from 50% the previous fall. Microsoft’s CEO put his own company at 20–30% a year earlier, rising steadily. You don’t have to be Google-scale for this to matter to a new hire — you just need enough agent-authored code in the history that “who wrote this and why” stops being answerable by instinct. I put my own numbers on this shift, on a much smaller repo, in 4,154 Commits in Six Months With AI Agents — the commit graph looks like a much bigger team than the one that exists.

None of what follows replaces a CLAUDE.md. That file is the artifact — the executable tribal knowledge a new hire and every agent session both read on day one, and I’ve written the case for treating it as onboarding documentation rather than config in Your CLAUDE.md Is the Onboarding Doc You Never Wrote. This post is the process around that artifact: what a manager and a senior actually do, week by week, to turn a human into a trusted contributor to a codebase that’s already half machine-authored before they show up.

First-PR review calibration when half the diffs are agent-authored

A new hire’s first PR is normally a low-stakes, high-signal event. You’re not evaluating whether the code is perfect — you’re calibrating how they take feedback, whether they ask the right questions, whether they understood the ask. That calibration breaks quietly when the reviewer doesn’t know the diff’s provenance.

Here’s the failure mode I watch for: a newcomer submits a PR where the bulk of the diff was agent-generated, lightly reviewed, and pasted into place. The code passes CI. It looks clean — arguably cleaner than what a nervous new hire would write by hand in week one. A reviewer who doesn’t ask “how much of this did you write versus generate and check” grades the PR on the artifact and misses the actual thing they’re supposed to be measuring, which is whether this person can evaluate code, not whether they can produce it.

The fix isn’t banning agent use on early PRs — that’s both unenforceable and backwards, since fluency with agents is table stakes now. The fix is changing what the first-PR review asks for:

• Require a one-paragraph “how I built this” note on the PR, not as a gotcha, but as the same signal a live coding round used to give you. Which parts were generated, which were hand-written, what you changed after reading the generated version, and why.
• Ask the newcomer to defend one specific decision in the diff out loud, in review or a short sync — not the whole PR, one line or one function. If they can’t explain why a particular approach was taken, that’s the finding, regardless of who typed it.
• Grade the review comments they leave on other people’s agent-authored PRs, not just the code they submit. Reading and catching problems in someone else’s (possibly machine-generated) diff is a closer proxy for the actual job now than writing a clean function from scratch.

This isn’t a lower bar. It’s a different bar, and pretending the old one still measures the same thing is how a team ends up with someone who can shepherd an agent to working code but can’t tell you why it’s right.

“Who wrote this” — building the transparency norm before it’s needed

Ambiguity about authorship isn’t just an onboarding problem, it’s a team-wide health problem that gets exposed hardest by a new hire, because they have no context to fall back on. A senior engineer looking at a weird function in a familiar file has priors: that’s probably legacy, or that’s Dave being clever again. A new hire has none of that. They just see code, and they can’t tell if it’s a deliberate pattern to learn or an agent’s confident guess that nobody caught.

The norm worth building, before a new hire arrives, not after they’re confused by it:

• Commit messages and PR descriptions state authorship plainly — not every commit needs a disclaimer, but PRs that are majority agent-generated should say so, the same way you’d note “ported from the old service” or “pairing with contractor X.” This is cheap and it’s the single highest-leverage transparency move available.
• A newcomer is explicitly told it’s safe to ask “was this agent-written” in review, without it reading as an accusation. On a team where that question feels loaded, new hires learn to stay quiet about their own confusion, which is the opposite of what week one is for.
• Nobody hides behind “the agent wrote it.” Authorship transparency cuts both ways — stating that code was agent-generated doesn’t excuse skipping the review, it’s context for a better review. The engineer who merged it still owns it. Make that explicit to a new hire early, because the alternative — an org where “the agent did it” becomes a diffusion-of-responsibility shrug — is a culture problem you don’t want them learning by example.

I’ve written more broadly about why this kind of transparency is the actual operating system underneath any team, human or agent, in Trust Is the Operating System — the same three-way trust that has to run between you, your team, and the mission runs here too: a new hire has to trust that “who wrote this” is a question they’re allowed to ask, and the team has to trust them enough to hear an honest answer.

Mentorship, recalibrated: what a senior teaches when the agent writes the boilerplate

The classic mentorship model assumes the junior’s first six months are spent writing a lot of straightforward code under supervision — CRUD endpoints, test scaffolding, the un-glamorous 70% of the work that builds muscle memory for the codebase’s shape. That 70% is exactly the part an agent now does fastest and best. If a senior’s mentorship plan is still “give them the boilerplate tickets to build confidence,” they’re handing a new hire tasks the agent would’ve done in the same PR anyway, and the newcomer learns nothing that a code review of the agent’s output wouldn’t have taught them faster.

What a senior needs to teach instead, deliberately, because it won’t happen by osmosis anymore:

• Judgment about when not to reach for the agent. The specific corners of the codebase — the billing path, the auth boundary, the one gnarly reconciliation job — where hand-written, deeply understood code matters more than fast output. A new hire won’t know which corners those are unless someone tells them, because the codebase itself won’t visibly flag it.
• How to read a diff for intent, not just correctness. Agent-generated code that passes tests can still solve the wrong problem elegantly. Teaching a new hire to ask “does this address what the ticket actually needed, or just what it literally said” is a mentorship muscle that matters more, not less, when the code itself looks polished by default.
• The undocumented reasons things are the way they are. This is the part a CLAUDE.md captures for an agent’s context window but a human still needs walked through in conversation — not because the file is wrong, but because a new hire benefits from the story behind the fact, and an agent doesn’t need the story to use the fact correctly.
• How to disagree with an agent’s output in a PR they’re reviewing, not just one they wrote. This is a skill nobody had to teach five years ago because there was no confident, fluent, occasionally-wrong collaborator producing plausible-looking diffs at volume. It’s now one of the highest-value things a senior can model in a pairing session.

If you’re hiring a staff-level engineer into this environment specifically to carry this kind of mentorship load, the calibration matters even more than usual — I laid out the three flavors of “staff engineer” and which one an AI startup actually needs in How I’d Hire a Staff Engineer at an AI Startup. The wrong flavor in this seat is a senior who mentors like it’s 2019, teaching a new hire to write boilerplate a machine already writes for free.

Standards drift: what a newcomer learns from the agent versus what only a human holds

Every codebase has two layers of convention. The first layer is enforced — a linter, a formatter, a CI check, or increasingly, an agent instructed to follow specific patterns every time it touches a file. The second layer is held — conventions that exist because a senior engineer remembers a past incident, a design decision that never got written down, or a “we don’t do it that way here” that lives entirely in tribal memory.

Agent-heavy codebases make the first layer look more complete than it is. A new hire watching agent-generated PRs land cleanly, formatted correctly, following the obvious patterns in the file, can reasonably conclude the codebase’s standards are fully captured somewhere. They aren’t. The agent is enforcing what it was told to enforce — usually in a CLAUDE.md or equivalent, per the framing in Your CLAUDE.md Is the Onboarding Doc You Never Wrote — and staying silent about everything nobody thought to write down. That silence reads, to a newcomer, as “there’s no rule here,” which is the most dangerous kind of standards drift: not a rule being broken, but a rule that was never visible in the first place.

The detection process worth running deliberately, rather than hoping a new hire stumbles into it:

1. Have them audit one week of merged PRs and flag anything that looks inconsistent — not to find bugs, but to find places where two “correct-looking” PRs did the same thing two different ways. Ask a senior which way is actually preferred and why. Half the time the answer is “either is fine.” The other half is where a held convention just surfaced.
2. Ask them, explicitly, in week three or four: “what’s a rule here you’ve inferred from the code that nobody’s told you out loud?” Whatever they answer is either confirmation the pattern is real, or a chance to correct a wrong inference before it compounds into their own future PRs.
3. Treat every “I assumed the agent would catch that” moment as a CLAUDE.md gap, not a hiring gap. If a newcomer gets burned by a convention the agent didn’t enforce and nobody told them about, the fix is adding it to the shared instructions everyone reads — human and agent — not just correcting the individual.

The week-by-week shape

Not a 30-60-90 template — those assume the ramp is uniform and the codebase is static. This is shaped around when agent fluency versus judgment actually gets tested.

Week 1 — Read before you write, and read authorship-aware. The new hire reads the CLAUDE.md (or equivalent) alongside the actual codebase, and is told explicitly which parts of the recent history are agent-heavy versus hand-written, so they’re not building intuition on a false assumption. No PRs yet. Their only output this week: a list of three things the code does that the CLAUDE.md doesn’t explain, handed to their onboarding buddy.

Week 2 — First PR, small and bounded, with the “how I built this” note. Scoped tight enough that agent-assist or not, the review is fast and the transparency norm gets exercised immediately, before habits form either way.

Weeks 3–4 — Standards-drift audit. The exercise above: one week of merged PRs, flag the inconsistencies, ask what’s inferred versus told. This is also when a senior should start pairing specifically on judgment calls — the “should this be hand-written” corners of the codebase — rather than more boilerplate tickets.

Weeks 5–8 — First PR review of someone else’s agent-authored diff. This is the real test, not the first PR they wrote. Can they read a plausible-looking diff critically, ask “does this solve what the ticket needed,” and push back on something that passes CI but misses intent? This is where you find out if you hired someone who can operate the agent or someone who can supervise it — a distinction with a growing gap between the two.

Weeks 9–12 — Own a slice that includes at least one “don’t reach for the agent” corner. By now they should know which parts of the system are hand-written on purpose. Give them ownership of one, with a senior available but not hovering. Their judgment about when to say no to the fast path is the actual signal you’re now able to measure, because they’ve had two months of evidence to form it from.

The shape holds whether the newcomer is a junior or an experienced hire from a less agent-heavy shop — the second group often needs weeks 1–2 more than the first, because the disorientation isn’t about engineering skill, it’s about a codebase that doesn’t behave the way their instincts predict.

Hiring for this before you onboard for it

None of this process fixes a bad hire. If the underlying hiring bar is still tuned for whiteboard recall instead of judgment under ambiguity, this onboarding playbook is applying good process to the wrong input — I’ve made the broader case against that mismatch in The Perfect Hire Is Killing Your Team. What this process actually needs from a candidate isn’t agent fluency (that’s teachable in week one) — it’s the same slope-over-intercept judgment that mattered before agents existed, applied to a codebase where the volume of plausible-looking output is higher and the cost of skimming instead of reading is higher with it.

If you’re building out an engineering org where this is already the reality — where new hires are reading diffs they can’t attribute on sight, and your existing onboarding process still assumes 2019 — this is exactly the kind of process gap a fractional engineering leader closes fast, without a six-month re-org. If that’s where you are, let’s talk.