A new engineer's first week has always been a trade-off between reading documentation nobody trusts and asking questions that interrupt everyone else. We tried something different this year.
The old week
Day one was a README, an architecture document of uncertain age, and a list of people to ask. It worked, slowly, and the speed depended entirely on how patient the team happened to be that week.
What we tried instead
We gave new joiners a coding agent with access to the repository and a standing instruction: ask it to explain any file before asking a person. Not to write code — to explain what exists and why, with citations to the actual files.
- It answered the small questions well — what does this function do, where is this value used elsewhere, why does this table have two similar-looking columns.
- It answered the "why" questions badly — decisions made eighteen months ago for reasons not recorded anywhere in the code are not recoverable from the code, by a model or a person.
- It reduced interruptions to the team, measurably, in the first three days specifically.
The gap it exposed
Every question the agent could not answer well was a decision that existed only in someone's head or in a Slack thread nobody would find again. We started treating "the agent didn't know" as a signal to go write the decision down, which has quietly improved our documentation more than any documentation initiative we had tried directly.
Using an agent for onboarding did not replace the senior engineer's time. It concentrated that time onto the questions actually worth their attention.
What we would not do
We do not let new joiners submit agent-generated code in their first week without a human pairing on it. Explaining the codebase and writing into the codebase are different activities, and the second one still needs someone who has earned the judgement calls the first week is meant to build.
The measurable outcome
Time to first meaningful pull request fell by roughly a third on the two hires we have run this with so far. Small sample, but consistent with what we would expect: less time spent finding the right file, more time spent understanding why it looks the way it does.