TL;DR
A new engineer on an AI-heavy team can ask an agent where things live on day one and merge changes within a week, so output no longer shows whether onboarding worked. Sort what the repository can teach from what only a teammate can, give the newcomer a guided first change whose plan and explanation are theirs, and weeks later set an explanation, prediction or debugging task with the agent switched off. Its result shows what they understand, and where the gaps are.
What ten merged pull requests do not show
DX, which sells engineering-productivity measurement, reported in its AI-assisted engineering Q4 impact report that at six multinational enterprises, between July and September 2025, new hires reached their tenth merged pull request in 49 days with daily AI use, against 91 days with none. It is vendor data, a correlation, and a count of merges. It cannot say whether the person behind those pull requests could explain them, or find a bug in one without help.
Team leads are asking about that gap. In January 2026 a developer who leads juniors asked on Hacker News how other team leaders balance AI coding tools with junior developers' growth. They work mostly through Claude Code, management expects shorter deadlines, and they wondered whether their juniors would ever build the debugging intuition they had built by hand. In March 2026 an Ask HN thread on the biggest pain point when joining a new developer team, opened by someone planning an AI tool to answer new joiners' questions, drew replies pointing elsewhere. One said tools already answer code questions reasonably well and the hard part is the people. Another called the real problem "inheriting judgment": knowing which files to trust, which patterns are intentional and who quietly owns what.
One controlled study bears on how a newcomer uses the agent. In Anthropic's randomized trial of 52 mostly junior developers learning an unfamiliar Python library (research summary, January 2026), those who delegated code generation averaged below 40% on the follow-up quiz, while those who asked conceptual questions, or generated code and then asked for explanations, scored 65% or higher. Each pattern covered two to seven people: a hint for designing tasks, not a finding about your team.
Sort what the repository can teach from what a teammate has to
Before the first day, list the questions a newcomer will have and decide where each answer should come from. An agent finds facts held in code, configuration, history and documents quickly, and the newcomer checks its answer against the files it cites. Judgements live in people.
Comparison
| Ask the repository through the agent, then check the cited files | Ask a named teammate |
|---|---|
| How to build, run and test the project locally | Why a design was chosen when no record says so |
| Where a request enters and which modules it passes through | Which patterns are deliberate and which are accidents nobody has fixed |
| The data model, configuration and conventions in use | Which areas are fragile, and what has broken there before |
| What the agents' instructions file allows and forbids | Who owns which part, and who reviews what |
| Which checks run on a pull request | What the business cannot tolerate, and what can wait |
The second column is not a documentation failure. A Microsoft case study of onboarding, built on interviews with 32 developers who had recently moved teams and 15 engineering managers (Ju et al., ICSE 2021), notes that not all information is available as documentation, so new developers have to seek the team for help; of 18 interviewees who had a mentor or onboarding buddy, 14 found the mentor helpful. The study predates coding agents, which do not move a team's unrecorded judgement into the code.
Name one teammate as the newcomer's first contact for the second column, and give them the time. When an answer proves stable, such as the reason behind a design, write it into the repository, where the next newcomer's agent can find it.
Paqad is not a teaching or skills-assessment system and does not replace that teammate; it helps with the first column. A question about the project goes to a workflow in which the AI reads the documentation first, then the code, and changes nothing, so the answer is only as good as that documentation and the model. Each code change also leaves a folder holding its plan, frozen specification, review and check results, which a newcomer can read to learn why earlier changes look as they do. Paqad's documentation explains how project questions are answered and what those answers do not guarantee.
What to understand before delegating the first change
The newcomer needs enough of the system to judge one change. Before handing any change to an agent, they can:
- Run it. Build, start and test the project themselves, and know how long the checks take.
- Trace one real request. Follow it from entry to storage and back, with the agent's trace as a guide, confirming each step in the code or a debugger.
- Name the blast radius. Say which callers, data and configuration the area they will change touches.
- Say what would catch a mistake. Point to the test or signal that fails if the change is wrong, or admit that there is none.
- Know the house rules. Read the instructions file the team's agents load, including what they may not do.
Tool setup is the quick part. Claude Code's /team-onboarding command, added in version 2.1.101, turns an experienced teammate's last 30 days of sessions, commands and MCP server usage into a guide a newcomer can paste in to get set up (command reference). It copies a setup; it cannot say which module is fragile. The article on starting a coding agent on an existing codebase without breaking working features describes read-only first steps that suit newcomers too.
A guided first change the newcomer owns
Twelve of the 15 managers Ju and colleagues interviewed raised complexity gradually, starting with simple bugs or configuration changes in the first week, and the authors recommend that approach for junior developers. A first change in an agent-heavy team can add one rule: the agent may draft code, but the reasoning has to be the newcomer's.
- The mentor picks a small, real, low-risk ticket with a known good answer, in the newcomer's future area.
- The newcomer writes the plan before asking for code: the behaviour to change, the files involved and the test that will prove it. Reviewing the plan takes the mentor minutes.
- The agent drafts within that plan. Claude Code's Learning output style shifts more to the person: it writes routine parts and leaves pieces with a real design decision, such as error handling or business logic, marked
TODO(human)for them to write. - The newcomer explains the diff to the mentor before review, section by section. Any part they cannot explain goes back to step 2 instead of into the pull request.
- Review goes to the newcomer. They answer the comments themselves, and reviewers ask about reasoning as well as code. Rotate reviewers so the newcomer meets more of the team.
Ownership shows in step 4. A newcomer who can say why the change is shaped as it is has learned something about the system; one who can only repeat their request has learned the prompt.
Weeks later, a task with the agent switched off
Prompt familiarity produces working changes, so merge history cannot reveal it. After a few weeks of guided changes, set one task in the area the newcomer has worked in, with the agent off and a fixed time limit:
- An explanation for someone who was not there. To a teammate who did not work on those changes, the newcomer explains how a request moves through the area, what can fail and what they would check first. Include one question whose answer came from a person, such as why the area is built that way.
- A prediction before a run. Describe a small change, such as a different input or a removed guard, and ask what will happen before anyone runs it. Then run it. An agent can fix a failure after it appears; predicting the failure takes a model of the system.
- A bug the team has already solved. Revert its fix on a throwaway branch and ask the newcomer to find the cause.
Note where they got stuck, not a score, and decide the next step:
Decision guide
| What the task showed | Next step |
|---|---|
| Explanation and prediction held up | Widen the scope: larger changes, lighter plan review |
| Fixes came easily, predictions did not | More guided changes in that area, with the plan review kept |
| No account of why the area is built as it is | A session with the teammate who knows, then write the answer down |
Frequently Asked Questions
How do we onboard a new engineer when the team increasingly works through AI agents?
Plan for two outcomes: a working setup, which agents and tools now make quick, and a person who can explain and debug their area, which still takes a mentor's time. Make the second the exit criterion: onboarding ends when the newcomer handles an agent-off task in their area, not on a date or at a pull request count.
What system understanding does the engineer need before delegating their first change?
Enough to notice when the agent is wrong. If the newcomer cannot name a test or signal that would fail on a bad version of their change, writing that check is a good first task in itself, and it often teaches the area faster than the change would.
Which explanations should come from code and documentation, and which require a teammate's judgement?
A rough test: if the answer would be the same whoever you asked, it belongs in the repository, where an agent can find it. If it depends on intent, priorities, history or people, ask a teammate. When that answer stays stable, write it down so it moves into the first group.
How can early tasks combine AI assistance with genuine ownership and feedback?
Keep the agent's role visible in the pull request, so reviewers know which parts the newcomer wrote, which they directed and which they accepted, and can aim their questions accordingly. Most developers surveyed in the Microsoft study also agreed that tasks requiring work with different teammates help newcomers build connections, so pick early tickets that need input from more than one person.
What independent debugging or design task would show that onboarding produced understanding rather than prompt familiarity?
A small design question works as well as a bug. Ask how they would add a nearby feature, which files it would touch and what could break, and compare the answer with a senior engineer's. Repeat it after a couple of months; a gap that persists in the same area usually points to missing documentation or mentoring rather than to the newcomer.