How to onboard a new developer to a Claude Code team in one day

When a team uses Claude Code, a new developer joins twice. The person joins, and so does their agent. The person has weeks to learn how the team works. Their agent starts writing code on day one, and it only knows what the repository tells it.

That makes onboarding faster if the team's way of working is written down where the agent reads it, and slower if it isn't: the new hire's first PRs arrive quickly, look plausible, and ignore half the team's conventions.

Here is a one-day plan that gets both of them ready.

Before day one: make the repository explain itself

Most of the work happens before the new developer arrives. Check that the repository carries three things.

A shared CLAUDE.md at the root. Claude Code reads it automatically at the start of every session. It should hold the commands (install, run, test, lint), the folder layout, a reference implementation to copy, the ownership of each area, and the handful of rules the team actually enforces. If you don't have one, our CLAUDE.md template for teams is a starting point.

A committed .claude/settings.json. This is where shared permissions live: which commands Claude Code may run without asking, and which it must never run. Committing it means the new hire's agent starts with the same guardrails as everyone else's, instead of whatever they click through in the first hour.

Folder-level CLAUDE.md files where the rules differ. If the payments service or the data pipeline has its own conventions, put them in a CLAUDE.md inside that folder. Claude Code picks it up when working there, and the root file stays short.

A quick test: ask someone who has never seen the repository to open Claude Code and ask "how do I run the tests for one file?" If the answer is wrong, a new hire's agent will get it wrong too.

Morning: set up the machine and the personal layer

1. Install and sign in. Install Claude Code, sign in, and clone the repository. Run it once from the repository root so it picks up the shared files.

2. Read the shared CLAUDE.md together. Spend 20 minutes on it with the new developer. This is the fastest overview of the codebase you have, and it is the exact context their agent will work from. Anything they find confusing is probably confusing to the agent too, so fix it on the spot.

3. Set up the personal layer. Personal preferences belong in the developer's own ~/.claude/CLAUDE.md, not the shared file: how verbose they like answers, their editor habits, the language they prefer explanations in. Personal permission tweaks go in .claude/settings.local.json, which stays out of version control. Make the split explicit on day one, so team rules don't get edited to suit one person.

4. Show the team's commands. If the team keeps custom slash commands in .claude/commands/ (for example a /review or /new-endpoint command), walk through them. They are the team's habits in runnable form.

Midday: a guided first task

Pick a small, real task with a clear finish line: a bug with a reproduction, or a small endpoint that follows an existing pattern. Not a toy, and not anything that crosses team boundaries.

Have the new developer do it with Claude Code while a teammate watches for 30 minutes. The point is not the code. It is to see how the agent behaves in your repository:

• Did it follow the reference implementation, or invent its own structure?
• Did it run the right test command the first time?
• Did it stay inside the files the task needed?
• Did it stop and ask where the rules say to ask (schema changes, auth, billing)?

Every "no" is a gap in the shared files, not a mistake by the new hire. Write it down.

Afternoon: the first PR and the first fix to the instructions

1. Open the PR the normal way. Same template, same checks, same reviewers as everyone else. Agent-written code from a new hire gets the review any new hire's code gets.

2. Turn the gaps into edits. For each "no" from the guided task, add or fix one line in the right CLAUDE.md. Let the new developer make the edit and open it as a second small PR.

This is the most useful thing a new hire can do on day one. They are the only person on the team who sees the repository with fresh eyes, and their agent is the only one that shows exactly what the written instructions are missing.

End of day: what to check

By the end of the day the new developer should have:

• Claude Code running against the repository with the shared settings
• A personal ~/.claude/CLAUDE.md that holds their preferences, not team rules
• One merged or reviewed PR for a real task
• One PR that improves the team's instructions

If all four are true, their agent now works the way the team works, and the instructions are a little better for the next person.

Why this matters more as the team grows

On a team of three, conventions live in people's heads and spread in conversation. On a team of thirty, each developer's agent is making hundreds of small choices a day based on whatever the repository says. Onboarding is the moment the gap between "how we work" and "what is written down" is easiest to see, so it is the best moment to close it.

Starting from the docs you already have

The slow part is usually the first version of the shared files. Most of it already exists in your onboarding guide, your engineering handbook, and the page about who owns what. It just isn't in a form the agent reads.

That is what we built AI Workspace Builder for. You upload the docs your team already has, and it generates the CLAUDE.md, a profile for each role, and an install script in 15 to 30 seconds. There's one free trial workspace, no card required.

Either way, the next new hire is the best test you have. Watch what their agent gets wrong on day one, and write it down.