Onboarding has always been expensive. A new engineer joins, spends weeks getting their bearings, and the cost is pretty much invisible because it's distributed across the existing team's time. What makes it bearable is that someone on the team understands the code well enough to explain it.
That way of onboarding is breaking quietly. As teams generate more code than they read, organizational knowledge of why the codebase is the way it is erodes. The original author didn't write it - they prompted it. They may have tested it. They almost certainly didn't read it closely enough to internalize the decisions it encodes.
When the next hire arrives and asks "why is it structured this way," the honest answer increasingly is "I'm not sure." Not because the team is careless, but because comprehension was never the bottleneck that mattered. Speed was.
The engineer who built the feature on a Tuesday afternoon can demonstrate that it works. Whether they could explain it to a new colleague six months later, defend its structure under pressure, or recognize when a change violates an assumption it depends on - that's a different question. For AI-generated codebases, the answer is increasingly no.
We need to rethink the purpose of onboarding in our organizations. At sipgate, I've always been a proponent of using the smallest possible definition: I believe onboarding shouldn't take longer than two weeks and it should be restricted to just two goals: 1) How to get anything done in this specific organization and 2) How our customers tick. Both are things you will never read about in a book, or learn at school. That's a pretty high bar. In my view of optimal onboarding, technical knowledge or concepts about codebases should have never been included. That stuff should be written down somewhere, preferably in RfC documents. Now that most teams are using agentic coding, it makes even less sense to waste all this time detailing out technical concepts in 1:1s that may change by tomorrow morning (possibly without any human interaction). Instead, it's time to double down on those RfCs. And yes, these are also readable by an AI.
Thoughts? Find me on Bluesky.