Onboarding in the AI age: When new developers learn the system from a model that doesn’t know it

A new colleague, an extra adviser

A new developer wonders about something, looks around, and asks whoever seems least busy. The answer comes with context: “We do it this way – it’s tied to the old integration, long story.”

That conversation still happens. But the newcomer now has an AI assistant to ask as well. It can make getting started easier: navigating unfamiliar code, explaining a pattern, or preparing a question for the team.

The difficulty comes when a plausible explanation rests on assumptions that don’t hold in your system. The assistant might suggest simplifying an integration without knowing the constraint that made it necessary. The new developer has no reason to know about it yet either.

The gap between “best practice” and “our practice”

In established systems, there’s often a gap between how things “should” be done and how they actually are. Much of it comes down to history, compromises, and deliberate choices, as I described in How to evaluate and modernize an existing codebase (in Norwegian).

An experienced colleague can explain the background. For the newcomer, it may only emerge in review: the solution is tidy, but it doesn’t fit how the rest of the system works. It’s easy to spend the time correcting the code and forget to explain the missing premise.

As a tech lead, investigate it with the newcomer. Is the explanation missing from the documentation? Is it out of date? Did the assistant have access to it, and did it actually read it? Or did the model have the relevant information but interpret it incorrectly?

These are different problems, and they need different responses. More documentation does little good if the tool can’t find what you’ve already written.

Onboarding as a litmus test

When a newcomer and an experienced colleague understand the same task differently, you have something concrete to investigate. It may reveal knowledge that only exists in people’s heads. It may also show that the team’s own practice is unclear or ready to change.

The advice from The Quiet Responsibility applies here too: start by listening. Ask the newcomer to show how they arrived at the solution, and explain the considerations behind the team’s approach. That lets you examine the proposal and make the reasoning available to the next person who asks.

Make the context readable – for humans and models

1. A short introduction to the repo

A context file can describe architectural principles, conventions, and deliberate deviations, with links to examples and decisions. AGENTS.md is supported by several coding tools. Still, check how your tool discovers and loads instructions, which files apply in the directory you’re working in, and whether it can access the documents you link to.

Be realistic about the effect, too. Gloaguen and colleagues at ETH Zurich tested coding agents with and without context files. In the settings they studied, the files did not generally improve task success, while inference costs increased by over 20 percent on average. The study gives no basis for assuming that such a file automatically produces better results.

Use the file to make important constraints explicit, and try it on real tasks. It gives the assistant instructions to follow. You still need to check whether it follows them.

2. TDRs that explain local choices

Document why you chose a solution, especially when it might look needlessly complicated to someone new. A TDR (Technical Decision Record) can explain the constraint, the alternatives, and what would need to change before reconsidering the decision.

That gives the newcomer more to work with than “that’s how we do it here”. It also gives the team a chance to check whether the reasoning still holds.

3. Documentation where it’s used

The principle from Standards that actually stick (in Norwegian) still applies: make it easy to find what people need in their work. Markdown next to the code can make it easier to update documentation alongside a change. But its location alone doesn’t ensure the assistant reads it.

If important knowledge lives in Confluence or another system, check access there too. Try the tool the newcomer actually uses, not just your own account.

4. Work through a task together

Have the newcomer and their buddy walk through one concrete task from the first week. What did the assistant propose? What assumptions did the proposal rest on? Find the relevant code or decision together, and check whether the explanation holds.

Leave room to question current practice, too. Perhaps the constraint no longer applies. Perhaps the newcomer has spotted a simpler solution. The buddy’s job is to help assess it, not just defend what’s already there.

The tech lead’s opportunity

Ask the newcomer to note a few examples of answers that didn’t match your practice. Set aside time after a couple of weeks to go through them together. Distinguish missing or outdated documentation from access problems and answers that were wrong despite relevant context.

Then you can prioritize: what caused the most rework? What might affect the next person who joins? Update an explanation, fix a link, or adjust an instruction, and check whether it helps with the task in question. The list becomes useful because you examine it together.

Knowledge that can be shared

AI gives new developers another way to explore the system. As a tech lead, you need to make sure that exploration also leads into conversations with the team.

That doesn’t require writing down the entire history before anyone can start. Begin with the choices the newcomer actually encounters, explain them, and make the reasoning easier to find. The aim is for the next developer to understand both the solution and why you still believe it’s right.