Think about how someone actually ramps up on a codebase. Not the wiki they were told to read. The real mechanism: they ask the person next to them. “Where does auth happen?” “Why is this service split in two?” “Can I touch this or will it explode?” The answers come from someone’s memory, and the new person slowly copies that memory into their own head. Six weeks later they can work without asking, and the loop repeats with the next hire.
That mechanism has a name people rarely say out loud when they praise it: onboarding against tribal knowledge. The map of the system lives in a few senior heads, and getting productive means transferring it, one question at a time, from their heads into yours.
It works, right up until it doesn’t. The person is busy. The person left, and took the map with them. The person misremembered, and now you both believe something false. And there is a new kind of new hire on the team that cannot use this mechanism at all: the agent.
The agent is the newest hire, and it can’t ask
Every session, a coding agent arrives on your codebase like a first-day engineer with no memory of yesterday. It does not know where auth happens or why the service is split. Unlike the human first-day hire, it cannot lean over and ask. It has no one to absorb the tribal map from. So it does the only thing available: it greps, reads a few files, and infers.
That inference is the source of most of the trouble people blame on the model. The agent breaks a caller it never saw, ignores a convention nobody wrote down, reimplements something that already existed one directory over. These are not reasoning failures. They are onboarding failures. The agent was dropped into a system whose map lives in heads it cannot read, and told to perform as if it had ramped up.
You feel this most when you run several agents at once. Each one is a new hire, every session, with no shared map between them. Tribal knowledge does not even have a body to live in here. There is no senior agent who remembers. If the knowledge is not written into something they can all query, it does not exist for them, and they will each rediscover the codebase badly, in parallel.
Tribal knowledge fails people too, just more slowly
It is tempting to treat this as an agent problem with a human workaround. It isn’t. Tribal knowledge was always a single point of failure. Agents just make the failure fast and obvious instead of slow and deniable.
When the only copy of “why is it built this way” is in one engineer’s head, that engineer is a bottleneck and a risk. Every ramp-up taxes their time. Every departure is a partial lobotomy of the team. The bus factor is a joke people make because the alternative is admitting how much of the system nobody actually wrote down. The reason it never felt urgent is that human onboarding is slow enough to hide it. You lose the map gradually, hire by hire, and blame the ramp time on complexity rather than on the fact that the map was never externalized.
So the goal is not “make agents onboard like humans.” Humans onboard badly too. The goal is to give both a better thing to onboard against.
Onboard against the graph
The alternative to a map trapped in heads is a map the system keeps outside of heads: a code knowledge graph built from the actual source. The relations a senior would recite from memory, this calls that, this depends on that, this exists because of that decision, are read off the code and made queryable.
Now onboarding changes shape for both kinds of new hire.
The new engineer stops routing every question through a busy senior. “What calls this” and “what breaks if I change it” are answered by the graph, on demand, correctly, at 2am, without interrupting anyone. The senior’s time goes to the questions that genuinely need judgment instead of the hundred that just needed the map. The human still learns, faster, and against something that doesn’t misremember.
The new agent gets, for the first time, something to onboard against. Before it changes the auth middleware, it queries the graph for what depends on it, the same query the human would ask the senior, and gets the real answer instead of a grep-and-guess. The map it always lacked now exists in a form it can read. Every session, every agent, the same true map.
That is the line worth keeping: onboard against the graph, not tribal knowledge. It is one sentence that happens to solve the human onboarding tax and the agent reliability problem at the same time, because they were always the same problem wearing different clothes.
What the graph can onboard you on, and what it can’t
Be clear about the boundary, because overselling it is how you lose people’s trust. The graph is excellent at the structural half of onboarding: what exists, what calls what, what depends on what, where the boundaries are, what breaks if you touch this. That half is enormous, it is most of the questions a new person actually asks in week one, and it is the half that used to burn a senior’s afternoon.
the graph answers
- what exists
- what calls what
- what breaks if changed
- where boundaries are
only humans hold
- why this architecture
- the political history
- deadline-forced calls
The graph is weaker at the why, at least the part of it that never made it into any artifact. Why the founders chose this architecture over the obvious one, what the political reason was for splitting a team’s ownership down a strange line, which decisions were made under a deadline everyone knew was wrong. Some of that can be captured, if the reasons behind decisions get recorded at the moment they are made and linked to the code they govern, which is exactly what turns a bare structure into something that can answer “why.” But some of it is genuinely tribal in the human sense, the stuff people learned by being in the room, and no graph invents what was never written down.
So the goal is not to fire the senior. It is to stop spending the senior on the hundred structural questions the graph answers better anyway, and reserve their scarce attention for the judgment and the unrecorded history that only a human carries. The new engineer onboards against the graph for the map and against the senior for the wisdom, and the agent onboards against the graph for everything it is allowed to, which is most of what it needs to stop breaking things.
The graph has to stay true, or you’ve just moved the tribe
One warning, because it is the way this goes wrong. A graph that someone maintains by hand is just tribal knowledge with extra steps. It goes stale, and then it lies to the new hire and the new agent with the added authority of looking official. The onboarding map is only trustworthy if it is derived from the system and stays current as the system moves, which is the whole argument for documentation that maintains itself. If keeping the map true depends on someone remembering to update it, you have not escaped tribal knowledge. You have written it down and let it rot.
Where PaellaDoc fits
This is why PaellaDoc builds the graph from your repo and keeps it downstream of the code. New agents query it before they act, so they stop onboarding by inference. And the same map is available to the humans, so ramp-up stops depending on catching a senior between meetings. The knowledge that used to live in a few heads, and leave when they left, lives in something the whole team, people and agents, can onboard against.
Who on your team is the single head your codebase’s map lives in, and what happens the week they’re on vacation? Tell me on the forum.
Frequently asked questions
Why do coding agents keep breaking code they’ve never seen?
Because every session they arrive like a first-day engineer with no memory and, unlike a human, no one to ask. So they grep, read a few files, and infer. Most of what people blame on the model is an onboarding failure: the agent was dropped into a system whose map lives in heads it can’t read.
What does onboarding against the graph mean?
Instead of transferring the system’s map from senior heads one question at a time, both new engineers and new agents query a code knowledge graph built from the actual source. “What calls this” and “what breaks if I change it” get answered on demand, correctly, without interrupting anyone, from a map that doesn’t misremember.
Can a knowledge graph replace a senior engineer for onboarding?
No. It covers the structural half of onboarding, which is most of week one: what exists, what calls what, what breaks if you touch this. It’s weaker at the why that never made it into an artifact, the political history and deadline-forced calls. Reserve the senior’s scarce attention for that, not the hundred structural questions.
How do you onboard AI agents to a large codebase?
Give them something to onboard against that isn’t tribal knowledge. Build the graph from the repo, keep it downstream of the code so it stays true, and have agents query it before they act. A map maintained by hand is just tribal knowledge with extra steps; it goes stale and lies with official-looking authority.