Onboarding engineers when half your team is an AI agent

A new engineer joins your team. By the end of week one, they have shipped three PRs. By the end of week two, two of those PRs have been quietly reverted because the patterns they used were three quarters out of date.

They didn't write the code wrong. Their AI agent did. And the agent learned everything it knows about your codebase in the last 90 seconds.

This is the new onboarding problem. Your hire is fine. Your onboarding doc is fine. Your agent is the variable nobody planned for.

Why traditional onboarding doesn't transfer

Classical onboarding assumes the new hire absorbs context over weeks: pairing sessions, code reviews, lunch conversations, the slow accretion of knowing why things are the way they are.

AI-paired onboarding doesn't work that way. The hire is productive on day one — productive in the dangerous sense, because they ship volume before they ship judgment. Their agent doesn't know:

• Which files are load-bearing.
• Which patterns you migrated off and shouldn't reintroduce.
• Which abstractions exist for legal or compliance reasons.
• Which "weird" code is intentional and which is genuinely broken.

The hire absorbs this through a year of code reviews. The agent never absorbs it at all.

What needs to change

1. Onboard the agent before the human

On day one, give the new hire's agent the same context their human onboarding gives them: the architecture overview, the load-bearing files, the deprecated patterns, the why behind the big decisions. If your senior engineer would mention it in a pairing session, write it down — once — and make every agent read it.

2. Treat AGENTS.md like a README

A repo-level AGENTS.md (or CLAUDE.md, or .cursorrules) is now the first thing your agent reads. If it's empty, every new hire's agent starts from zero. Good agents files include:

• Conventions: package manager, framework version, directory layout.
• Forbidden patterns: things you migrated off, with the reason.
• Required helpers: the wrappers, hooks, or utilities the agent should reach for.
• Testing rules: which tests must pass, which can be skipped.

3. Convert pairing sessions into briefs

When a senior explains something to a junior, that explanation should not vanish at the end of the call. Record it. Transcribe it. Generate a brief. Now the next hire's agent gets the same explanation — without occupying the senior's calendar twice.

4. Code review the agent, not the hire

When a PR comes back with a wrong pattern, the question isn't did the hire know better? It's did the agent know better? If the agent didn't have the context, the fix isn't to chastise the hire — it's to update the brief and make sure every future agent reads it.

The compound effect

Teams that get this right invert the bottleneck. Onboarding time drops — not because hires learn faster, but because the agents they pair with already know the codebase. Seniors can spend less time correcting AI-generated PRs and more time mentoring humans.

Teams that get this wrong end up in a worse loop than pre-AI: more code shipped, more reverts, more tribal knowledge that lives in fewer heads as seniors burn out fixing agent-generated mistakes.

The takeaway

Your new hire is going to ship more code in their first month than any hire before them. The question is whether that code reflects how your team actually works — or how an LLM imagines a team like yours might work.

Onboard the agent. The human follows.