A codebase that needs unwritten knowledge to understand fails two readers in exactly the same way: the engineer who joined last month and the AI agent you rolled out last quarter. Both can open every file. Neither can see the reasons. Most teams treat these as two separate problems, buy a tool for one and run an onboarding programme for the other, and then wonder why neither one fixes things.
It is one problem. And it gets expensive fastest in the place most companies are investing right now: a new team, in a new office, inheriting a system somebody else built.
The knowledge that never made it into the repository
The most important rules in a mature system usually live outside the code that looks like it owns them.
A discount rule sits in an event listener nobody thinks to open. A permission check lives in a policy class, but the exception to it lives in a scheduled job that runs at 02:00. A status value of 3 means “on hold” because someone decided that in a meeting years ago. I once traced a production bug to business logic hiding in database triggers, where no amount of reading the application code would ever have found it.
None of this is bad engineering in the moment. Each decision made sense to the people in the room. The trouble is that the room was the documentation, and the room does not ship with the code.
The result is a system you can only understand if you can read the original team’s mind. I have been walking into systems like that for fifteen years. AI made the problem fashionable. The cost is not new.
A new team feels it first, and feels it most
Distance turns missing knowledge into waiting time.
I co-founded Behind Methods in 2011 and spent the next fifteen years running engineering from India for systems owned by companies in Canada, Israel, Australia, the UK and the US. Some of those systems I built from the first line. Many I inherited, including a legacy lottery platform in Israel that had to be modernized before anything new could be built on it, and an Australian SaaS product that needed the same in 2024.
Every inherited system taught me the same lesson. The answer to the question blocking you is almost never in the code. It is in the head of someone nine or ten time zones away. So the question waits for the overlap hour. The answer arrives the next morning, half remembered. A two-hour task becomes a two-day task, and nobody records it as a delay, because on paper the engineer was busy the whole time.
Then the person who knew the answer moves on. That is the moment the real bill arrives, and it usually arrives in the middle of a handover that looked finished.
A new team does not slow down because the engineers are weaker. It slows down because it inherited the code without the reasons.
AI agents do not fix this. They make it louder.
An AI agent with access to a repository will answer questions about it confidently, quickly and often wrongly, for exactly the same reason a new engineer struggles: the knowledge it needs was never written where it can be read.
The difference is volume. A new engineer who is unsure asks someone. An agent that is unsure produces a fluent answer and a plausible pull request. On a codebase that runs on unwritten knowledge, adding agents means you produce more confident wrong answers per hour, and every one of them has to be caught by the few people who still remember why things are the way they are. That is why verifying code is now the real bottleneck, not writing it.
So the senior people who were supposed to be freed up by AI end up reviewing more, not less. The tool did not remove the dependency on them. It multiplied it.
What I do when I inherit a system
I do not start with documentation. I start with the questions that are already waiting.
The first move is to collect every question the new team has asked in the last few weeks, from chat, tickets and calls, and group them. A handful of areas almost always produce most of the waiting. That list becomes the plan for what gets written down, and it is written by the people who need the answers. Nothing gets documented that nobody asked about.
The second move is to sit with the person who knows the system best, before they move on, and ask one question: “What would a smart new engineer try to fix here, and break something?” The answers are the decisions that look wrong and are right. “We do not cache this page because prices change mid-session” is the kind of sentence that saves someone a week. Each one gets written next to the code it protects, with the reason, so the next reader finds it at the exact moment they need it. One hour of that conversation is worth more than a month of wiki pages.
The third move is to turn the expensive rules into walls. A written rule gets forgotten under deadline. So the few rules that cost money when broken become automated checks that fail the build. On the systems I led, I wrote custom checks that run in continuous integration and stop a merge when code crosses a boundary it should not cross. The new engineer and the AI agent hit the same wall, get the same message and learn the same rule. Next to those checks sits a short context file at the root of the repository: where things live, what not to touch, which conventions are deliberate. I work this way every day, and it is the first thing an agent reads.
Three moves, in that order, because each one removes a different kind of waiting: the question that waits for the overlap hour, the knowledge that leaves with a person, and the mistake only a senior reviewer would have caught.
This is a leadership job, not a tooling job
Deciding what a team needs to know is a judgment call about the business, and tools cannot make it.
Running a company for fifteen years teaches you that every hour spent writing things down is an hour not spent shipping. You cannot document everything, and a wiki nobody reads is worse than no wiki. So the question is never “what should we document?” It is “which rules cost us money, customers or trust when someone gets them wrong?” Answering that means understanding the product, the commercial pressure behind it and the people who will carry it next. I have stopped delegating certain decisions to AI for exactly this reason. It can read everything and still not know what matters.
The other half is people. I have trained a lot of engineers over the years, and the pattern held every time: the ones who became productive fastest were not the most talented. They were the ones who landed on a system where somebody had written down the why. Their first month went into building, not into waiting for the overlap hour.
That is the real return. A readable codebase is not a favour to the AI. It is how a team grows without the original team in the room.
A test you can run on Monday
You can measure how much of your system lives in people’s heads in about thirty minutes, with data you already have.
Open your team chat and take the last ten questions your newest team asked the older team. Skip the bugs and the outages. Keep the “where is”, “why does” and “how does this work” questions.
For each one, answer yes or no: was the answer written anywhere in the repository?
Then paste the same ten questions into the AI coding tool your team already uses, with access to the same repository, and count how many it answers correctly. You can check them easily. The right answers are sitting in the chat thread.
You now have two numbers. If most of the answers lived only in someone’s head, and the agent got most of them wrong, you have found the real reason the new team is slower than the plan said it would be. It is not the people and it is not the tool. And you have a number to take into the next planning meeting, which a feeling never was.
Run it again in a quarter. If the first number is not falling, the team is still growing at the speed of one person’s calendar.
A team scales at the speed its knowledge moves. Write the reasons down where the next reader will find them, whoever that reader turns out to be.