Onboarding people and AI agents to the same codebase

When I joined my first project at MadeCurious, the best-prepared new starter on it was not me but the AI. The team had written the agent a thorough welcome pack, with instructions on how to work in the codebase, maps of how its parts connect, rules that switch on only when the agent touches the files they govern, and guardrails around the things it must never go near. It was designed to make an agent useful in a long-running client system from its very first session, and as far as I could tell it did that job well.

I read the same pack, as any new starter would, and found that it told me a great deal about how the code fits together and almost nothing about what our users actually do with it, or why the system came to be shaped the way it is. It had been written, without anyone quite intending it, for a reader that would never think to ask why, and in those first days the only reader like that was the agent.

What finally helped me make sense of the codebase was much older technology: the engineers on the team sat down with me and walked me through the user flow and the design intent, explaining what each screen was for and why it worked the way it did. That kind of knowledge is hard to get from documents. Studies of working developers have found that questions about why code was written the way it was are among those they most often have to put off, and that the answers mostly live in people rather than in documents. That is exactly where I found them.

The black box

The app I work on sits in front of a black box, a third-party system that none of us can see inside, and a lot of what shapes our users' screens lives in that system's configuration: which fields a form shows, which of them are required, and which depend on others. The agent's welcome pack said as much, noting that the forms are data-driven from that configuration. What it never said was what that meant in practice, which is that the client's own team changes the configuration as their needs change. A regression test that walks through today's form, choosing this option and then that value, therefore carries an expiry date, and even before it expires it tells you nothing about whether the app is following its own rules.

Subhra, one of the engineers on the team, walked me through this in my first week, and it changed how I wrote our Playwright regression tests, which now check that the app does the right thing with whatever configuration it happens to be given.

I've trained models of my own, so I'm wary of saying an agent couldn't have got there, but I can say why it was unlikely to. An agent's output is sampled from a distribution conditioned on its context, which here meant the code, the docs and the prompt. That context held the fact without its consequence, and nothing in it pointed from one to the other, so the right design sat somewhere in the distribution with nothing to make it likely. Leave an agent to iterate until the tests pass and it will optimise for passing tests, which are only a proxy for what the tests are meant to protect, and Goodhart's law applies to a test suite as surely as it does to anything else.

Rather than leave that as an argument, I tested it on a small scale. I gave five fresh agent sessions the repository as it stood just before I wrote the rule in, welcome pack and all, and asked each of them for a Playwright test of the first step of a new registration. None of the five read the form's rules. Four hard-coded today's values from start to finish, and the fifth took whatever was offered for two of the fields while relying on today's values for the rest. They weren't careless, either, since one of them worked out from the code that changing one field clears the fields that depend on it. They simply wrote good tests of today's form, and nothing they had been given suggested the form might change.

After the walkthrough I wrote that meaning back into the repository's agent instructions, so every agent session there now starts with it, and I've come to think of this as the two new starters meeting in the middle from opposite ends.

The agent works upward from the code, and my reading of the research is that its brief should start there too. A recent preprint from ETH Zurich researchers found that overviews of a repository didn't help agents, and concluded that instruction files are useful for spelling out practices that differ from the norm.

A person works downward from the users and the reasons, which is how the C4 model draws software, starting from a system context meant for "everybody, both technical and non-technical people" and zooming in towards the code. Our two paths crossed at the black box, where the agent had the fact and I had learnt its meaning from people.

What goes in each pack

If the agent and I needed such different things, it follows that people will too, and what goes in a person's pack depends on who is joining.

An experienced engineer arriving on a new codebase mostly needs orientation rather than teaching. A short map of the system, the handful of rules that must never be broken, the reasons behind the big decisions recorded where those decisions were made, and a real change to ship early will do more for them than a guided tour, which can get in their way.

Classroom research has a name for something similar, the expertise reversal effect, in which help that supports a newcomer stops helping, or even hinders, someone who already knows the ground. In that sense the experienced engineer's pack looks a good deal like the agent's, with the reasons added back in.

A graduate meeting an architecture for the first time needs something closer to the opposite. The names and roles of the main parts should come before the system itself, in plain words, with any analogy tied straight back to the real term so that it doesn't harden into a misconception. A worked example of a real change helps, as do tasks that grow gradually harder and a buddy to ask, and the guide is better written, or at least reviewed, by someone who joined recently, because experts tend to underestimate how hard things are for a beginner. In one study of novices learning to wire a circuit, those taught by beginners did better at the task itself, while those taught by experts did better on a related task.

That is the kind of onboarding I ended up building for myself. I turned the raw codebase audits into Socratic seminars in which the agent asked the questions instead of giving the lecture. We began with the observable and unobservable systems (the ones we can see and the one we can't) and how they relate, and the stack's jargon came back in only as my understanding caught up. Alongside them I used interactive diagrams, built with tools I already had for this kind of work, so that I could click from the whole system down into its parts. The seminars in particular rest on two findings from learning research: people overrate how well they understand how something works until they try to explain it, and being prompted to explain tends to improve what they learn.

Then there are the colleagues who will never read the code but still need to talk about it with confidence, such as someone in marketing describing a change to a service, or a product that is still being built. They need the top of that map, the system context, written in plain words in the text itself rather than propped up by a glossary, because jargon makes writing harder for lay readers to process even when definitions are supplied. The most useful step for them is also the simplest, which is to explain the change back to an engineer before anything goes out.

Format matters as well. Long spoken explanations have done worse in experiments than the same words written down, so a narrated walkthrough works best when it is short and sits beside a written page. None of it survives without upkeep, either. Google's documentation improved once it moved its important docs into the source tree beside the code and gave each one a named owner, and on a smaller scale, every time an agent or a person gets something wrong because the context was missing, that is a gap in the pack worth fixing. I keep a log of exactly those moments, and they feed straight back into the welcome pack.

Why it matters more now

What a person adds at this stage of AI development is judgement and taste, more than the code itself. If that's right, onboarding has to cover the users and the design intent as well as the stack, and AI-generated docs can't supply that on their own. In my experience, proper onboarding is what lets a team use AI to build systems on purpose, rather than iterating until the tests pass.

There is early evidence that understanding is what's at stake. In a 2026 Anthropic study of 52 mostly junior developers, those learning a new library with AI help scored 50% on a comprehension quiz, against 67% for those who coded by hand, although the seven who used the AI only to ask conceptual questions still scored well, which the authors stop short of calling cause and effect. The authors also expect the effect to be stronger with agentic coding tools than with the chat assistant they tested.

Meanwhile our industry measures how quickly a new developer ships, often as the days to their tenth merged pull request, and even DX, which publishes that measure, notes that on its own it doesn't show "the depth of understanding new hires have of the systems they're touching". I suspect onboarding could be one of the biggest levers we have in the AI era, both on how effective a developer becomes and on how soon.

None of this means onboarding can't be automated, and the systems we build into a project to brief agents could brief people just as quickly, though never with a single pack. The best onboarding I had came from engineers who took the time to walk me through a system, and the most a pack can do is copy what they did. The next time someone joins a project, I'd like both new starters, the person and the agent, to find a welcome pack written for them, each one different and both built from the same facts.

The experiment

Five fresh Claude Code sessions (Opus 5.5), run on 16 October 2026. Each was given the repository as it stood just before the rule was written in, agent harness included, and the same request: a Playwright test for the first step of a new registration that fills in the form and checks it saves.

Sessions 1 to 3: Today's values, by name, for every choice. Read the form's rules: no.

Session 4: The first option offered for two fields; today's values for the rest. Read the form's rules: no.

Session 5: Today's values, by name, for every choice; worked out that changing one field clears the fields that depend on it. Read the form's rules: no.

Five runs, one model, one prompt and no running app: a tendency, not a rate.

One fact, three readers

The fact the story turns on: a form's fields come from settings in another system, and the client changes them.

AI agent: "In end-to-end tests, never hard-code form options. Read the fields from the form definition the page loaded, and check the app enforces 'required' and 'depends on' for whatever it gets."

Engineer: "The form's fields come from configuration in a system we don't own, and the client changes it. So our tests check the app follows its rules, not one fixed path through it."

Marketing: "The forms adapt to each client's own settings, so we test that the app behaves correctly whatever those settings are, not just for one version of them."

Sources

Each claim was checked against the source itself on 16 October 2026.

• "Why" questions are among those developers most often put off; the answers mostly live in people rather than documents: Ko, DeLine and Venolia 2007. Peer-reviewed, ICSE.
• None of five agents read the form's rules: The experiment above. Our own, 16 October 2026.
• Repository overviews didn't help agents; instruction files are useful for non-standard practices: Gloaguen et al., arXiv 2602.11988 v3. Preprint, ETH Zurich.
• C4's top level is for "everybody, both technical and non-technical people": C4 model: System Context. The model's own definition.
• Help that supports a newcomer can hinder someone with experience: Kalyuga 2007. Review, Educational Psychology Review.
• Experts underestimate how hard things are for beginners; beginner-taught novices did better at the task, expert-taught at transfer: Hinds 1999; Hinds, Patterson and Pfeffer 2001. Circuit-wiring task; checked against the abstracts.
• People overrate their understanding until they try to explain: Rozenblit and Keil 2002; Crawford and Ruscio 2021. Peer-reviewed; core effect held in a 2021 replication.
• Being prompted to explain tends to improve learning: Bisra et al. 2018. Meta-analysis of 64 reports, g = 0.55.
• Jargon is harder for lay readers to process even with definitions: Shulman et al. 2020. Science writing for non-experts; checked against the abstract.
• Long spoken explanations did worse than the same words written down: Leahy and Sweller 2016. Experiments with students.
• Docs improved once moved into the source tree with owners: Software Engineering at Google, ch. 10. Google's own account.
• 50% vs 67% on comprehension with and without AI: Anthropic, January 2026. Randomised; the conceptual-questions group was 7 people.
• Time to 10th PR doesn't, on its own, show understanding: DX, Developer ramp-up time continues to accelerate with AI (2026). DX's own analysis; quote checked word for word.