Onboarding Into a Codebase Nobody Fully Read
"Ask whoever wrote it" assumed someone did. Where code arrived complete in one commit and was approved rather than authored, the history holds no reasoning — and onboarding is where you find that out.
Onboarding assumed someone on the team could explain any part of the system, because someone had written it. In a codebase where a large share was generated and merged after review rather than authorship, that assumption weakens — and the standard onboarding process depends on it more than anyone noticed.
What changes
"Ask the person who wrote it" stops working. The reviewer approved it; that's a weaker form of knowing. They can tell you what it does and often not why it's shaped that way, because the shaping decisions were made by something that doesn't remember.
Code archaeology loses its evidence. Reading history to understand why something is the way it is works when commits reflect a person's evolving intent. When a module arrived complete in one commit, the history contains no reasoning.
Conventions become less meaningful. Idioms in a hand-written codebase encode team decisions. In a generated one they may just be what the model produced. A newcomer can't tell which patterns are deliberate and which are incidental — and following the incidental ones faithfully is a specific way onboarding goes subtly wrong.
Volume outruns comprehension. More code produced faster means more surface, less of it examined. A newcomer facing a large system where nobody has read most of it can't calibrate what's important.
✅ What to do instead
Write down the decisions, separately from the code. ⚠️ This becomes load-bearing rather than nice-to-have. Why this boundary, why this approach, what was rejected. If the code doesn't carry the reasoning and no author remembers, a written record is the only place it exists.
The version that works: short decision notes adjacent to the code, written at the time, saying why rather than what.
Mark what's load-bearing. A newcomer's biggest problem is not knowing which parts matter. An explicit map — these three modules are critical and carefully considered, these fifteen are generated CRUD — is worth more than any amount of general documentation.
Onboard through debugging, not reading. Give them a real bug in an important area. Debugging forces a model of how things actually work, and it's the fastest way to build one. Reading generated code produces recognition without understanding.
Have them trace a request end to end, by hand, through every layer. Tedious and it builds the systems model that nothing else does.
Assign ownership early. Being responsible for something is what motivates understanding it properly. A newcomer with no ownership reads passively.
💡 The deeper problem it exposes
If nobody can explain a module, that's not an onboarding problem — it's an operational risk that onboarding merely reveals. The person who can't be onboarded into it is the same person who can't debug it during an incident.
The check worth running independent of hiring: for each critical system, can at least one person explain how it works? Where the answer is no, that's a gap to close deliberately — someone reads it properly, writes down what they learn, and becomes the person who knows.
That's a resourcing decision competing with delivery, and it's the kind of thing that only gets funded after the incident that proves it was needed.
🔍 The onboarding signal worth watching
How long until a new engineer makes a change they're confident about, without asking someone to confirm it's safe?
If that number is rising, comprehension of the system is thinner than it was — and the same thinness affects everyone, not just the newcomer. They're just the ones who notice it, because everyone else has accumulated enough familiarity to paper over it.
The takeaway
Onboarding relied on someone being able to explain any part of the system. Where a large share was generated and reviewed rather than authored, replace that with written decision records, an explicit map of what's load-bearing, onboarding through debugging rather than reading, and early ownership. And treat "can anyone explain this module?" as an operational question rather than an onboarding one — the new person is only the first to discover the answer is no.