How to Onboard an Engineer onto an AI-Generated Codebase

Traditional onboarding runs on oral history. A new engineer reads code, gets confused, finds whoever wrote it and asks why. That loop breaks when a large share of the code was generated: there is no author, no reasoning to recall, and the git blame points at a colleague who accepted a suggestion eight months ago.

What is actually missing

Not the code — that is readable, often more consistently formatted than hand-written code. What is missing is the *why*: which alternatives were considered, which constraints forced this shape, and which parts are load-bearing versus incidental.

• Generated code rarely encodes intent, because intent lived in a prompt nobody kept.
• It often contains defensive handling for cases that never occur, which reads as evidence of a requirement that does not exist.
• Structure can be locally sensible and globally inconsistent, so patterns learned in one module mislead in the next.

Start with the decisions, not the code

The highest-leverage first week is spent on architecture decision records, not on the repository. Twenty ADRs explaining why the system is shaped this way will orient someone faster than a month of reading implementation — and where they do not exist, writing them is the single best onboarding task you can assign.

Teach the boundaries, not the internals

Internals of generated code change often and are cheap to regenerate. What is expensive and durable is the contract: what this service promises, what it depends on, what invariants must hold. Onboard at the boundaries and let implementation detail be looked up when needed.

Use comprehension tooling deliberately

AI explanation of unfamiliar code is genuinely useful for orientation and genuinely unreliable for correctness — it will describe what code appears to do, not what it does in this system with this data. Use it to build a map, then verify the parts the new engineer is about to change.

• Good: "summarise the responsibilities of this module" — a map, quickly.
• Good: "what calls this function and what happens if it throws" — a starting point for tracing.
• Risky: "is this safe to change" — a confident answer with no knowledge of your production behaviour.
• Risky: relying on an explanation of code the explainer also generated — the same blind spots produced both.

Write down what onboarding uncovers

Every question a new engineer asks is a gap in the record. The cheap habit that compounds: when a question is answered in a thread, the answer becomes a durable note attached to the subsystem it concerns. Without that, the next hire asks the same question and the team pays the cost again.

The uncomfortable signal

If nobody on the team can explain a subsystem, onboarding has surfaced a real risk rather than a training problem. Code that no human understands cannot be safely changed under time pressure, which is exactly when it will need to be. Treat that finding as an engineering priority, not an onboarding inconvenience.