Engineering onboarding checklist (with AI coding agents)
A practical engineering onboarding checklist for the first day, week, and month, plus how to use AI coding agents to learn a codebase and what they can't teach.
A senior engineer joins a team. By Friday their environment works, they've read the README, and they've fixed a typo. By week three they've shipped a feature that quietly reverses a decision the team made last year, because nobody told them and nothing in the code explains it. The onboarding covered the setup and the code. It skipped the context.
This checklist covers all three, with notes on using AI coding agents to learn faster, drawing on Anthropic's guide to understanding new codebases with Claude Code, checked on 16 November 2026.
Before day one
- [ ] Laptop ordered and set up
- [ ] Accounts: email, chat, code host, tracker, docs, cloud console
- [ ] Access to repositories, CI, staging
- [ ] Buddy assigned and told
- [ ] First week's calendar: team meetings, 1:1s, intro chats
- [ ] A starter task picked: small, real, mergeable in days
Day one
- [ ] Welcome from manager: role, team mission, first-month goals
- [ ] Meet the buddy
- [ ] Development environment running; tests pass locally
- [ ] Read: team README, architecture overview, how we work
- [ ] Join the channels that matter
Week one
- [ ] Codebase tour with an engineer (one hour, recorded if possible)
- [ ] First pull request merged
- [ ] Deployed something, even if tiny, through the normal pipeline
- [ ] Learned the review process, branching, and release cadence
- [ ] Read the key design docs and recent decisions for the team's area
- [ ] 1:1s with the PM, designer, and tech lead
Month one
- [ ] Shipped a meaningful change end to end
- [ ] Shadowed on-call for a rotation; read the main runbooks
- [ ] Owns one small area, service, or feature
- [ ] Gave feedback on the onboarding: what was missing, what was wrong
- [ ] Updated the onboarding docs with one fix
The last item keeps the checklist current: every new hire leaves it better.
Using AI coding agents to learn the codebase
An agent turns "read the code until it makes sense" into a conversation. Anthropic's docs suggest this flow in Claude Code:
- Open the project and start with a broad question: "give me an overview of this codebase."
- Narrow down: "explain the main architecture patterns," "what are the key data models," "how is authentication handled?"
- Find code: "find the files that handle user authentication," then "how do these files work together?"
Their tips: start broad and narrow down, ask about coding conventions, and ask for a glossary of project-specific terms.
A useful exercise for week one: have the new hire ask the agent to explain the area they'll work on, then check the explanation with their buddy. Wrong answers show where the code is confusing, which is useful for the team too.
What agents can't teach
An agent reads the code. It can tell a new hire what the system does and how. It can't tell them:
- Why the payments service uses a queue instead of direct calls
- What was rejected, so they don't propose it again
- What was agreed with other teams: the API format partners depend on, the deprecation date
- What changed recently in a meeting or Slack thread
That context lives in people's heads unless it's written down. Teams that keep design docs, ADRs, or a decision log onboard faster, because the new hire, and the agent they're using, can read the reasons.
Common onboarding mistakes
- No starter task ready. The first week turns into reading.
- Setup takes days. Script it; time it with each new hire.
- Docs that are wrong. Worse than none. Ask each new hire to fix one.
- Only code, no context. The new hire learns what but not why.
Where Lockstep fits
Lockstep keeps the why available. It captures decisions from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply to the code being changed, so a new engineer's first feature starts from the team's decisions, not just its code.
See how it works.
Sources checked 16 November 2026
Related reading
For rolling out Claude Code to a team, see how to roll out Claude Code to an engineering team. For team instruction files, see CLAUDE.md examples. For diagrams that help new engineers, see architecture diagram examples.
Frequently asked questions
- What should an engineering onboarding checklist include?
- Day one: accounts, hardware, development environment, and a buddy. Week one: a codebase tour, a first small merged pull request, and the team's processes. Month one: a meaningful project, on-call shadowing, and reading the key design docs and decisions.
- How long should engineering onboarding take?
- Plan for the first merged change within the first week and independent ownership of a small area within one to three months. The exact pace depends on the codebase and role; set explicit milestones so both sides know what on track means.
- How can AI coding agents help onboarding?
- A new engineer can ask an agent like Claude Code for an overview of the codebase, the main architecture patterns, the key data models, and where a feature lives. Anthropic's docs suggest starting broad, then narrowing, and asking for a glossary of project terms.
- What can't AI agents teach a new engineer?
- Why things are the way they are. The code shows what was built, not the decisions behind it, the options rejected, or the constraints agreed with other teams. That context has to be written down somewhere the new hire, and the agent, can find it.
- What is an onboarding buddy?
- A teammate assigned to answer questions, pair on the first tasks, and make introductions. It gives the new hire a person to ask without worrying about interrupting a manager.
Keep reading