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.

Below is a template you can copy into the root of a shared repo. Replace everything in <angle brackets>, delete what doesn't apply, and keep it short. Notes on each section follow.

The template

# <Project name>

<One sentence: what this repo is and who uses it.>

## Commands
- Install: `<command>`
- Run locally: `<command>`
- Test (all): `<command>`
- Test (one file): `<command> <path>`
- Lint and format: `<command>` (must pass before any commit)
- Never run: `<command>` (<why: e.g. resets the shared dev database>)

## Layout
- `<folder>/`: <what lives here>
- `<folder>/`: <what lives here>
- Reference implementation for new <services/components/endpoints>: `<path>`

## Ownership
| Area | Owner | Reviews required |
|---|---|---|
| `<folder>/` | <team> | <n>, at least one from <team> |
| `<folder>/` | <team> | <n> |

## Rules
- Follow the pattern in `<reference path>` for new <things>. Do not invent a new structure.
- <Database> schema changes: write the migration and open a PR. Never apply it directly.
- Anything touching <billing/auth/data deletion>: stop and ask before writing code.
- Dependencies: patch upgrades are fine. Minor or major upgrades need a separate PR.
- If you can't verify something (a command, an API, a config value), say "I haven't verified this" and stop.

## Standards
- Test coverage on new code: <n>% minimum
- <Language>-specific: <e.g. no `any` in TypeScript, type hints on all public functions>
- Commit messages: <convention, e.g. Conventional Commits>
- PR size: under <n> lines changed where possible

## Glossary
- **<Term>**: <what it means here>. Not "<banned synonym>".
- **<Term>**: <what it means here>.

## Definition of done
- Tests pass locally and the linter is clean
- The change follows the reference implementation
- The PR description explains what changed and why, in plain language

That's the whole file. If yours is much longer, read on.

What each section is for

Commands

This is the section that pays off fastest. Without it, Claude Code guesses the commands, and a plausible guess (npm test in a pnpm monorepo, pytest without the right flags) wastes time on every task.

The "Never run" line matters more than it looks. One destructive command that's easy to type, like a database reset or a deploy script, is worth naming explicitly.

Layout and the reference implementation

Don't describe the whole folder tree. The agent can read it. Name the folders whose purpose isn't obvious, and point to one existing file that shows the right way to do things.

"New endpoints follow the structure of api/orders/" gets better results than a page describing your architecture. Models copy examples far more reliably than they follow descriptions.

Ownership

In a team repo, the most expensive agent mistake is a change that crosses team boundaries: a refactor that touches three teams' code in one PR. An ownership table lets the agent notice the boundary and split the work, or ask first.

Rules

Write rules as short imperatives. "Never apply schema changes directly" is followed. "We generally prefer that schema changes go through review" is not.

Keep the list to the rules that are actually broken. A rule nobody would break anyway is noise that dilutes the ones that matter.

Standards

Numbers beat adjectives. "Clean, well-tested code" changes nothing. "80% coverage on new code" and "no any types" can be checked, by the agent and by your reviewer.

Glossary

This is the section most teams skip and most need. When the agent invents its own names for your domain concepts (a "customer" becomes an "account holder" in one file and a "client" in another), the codebase slowly fills with inconsistent vocabulary. A short glossary, including the synonyms you don't want, stops that.

Definition of done

Tell the agent what it has to check before it says it's finished. This turns "done" from a claim into something it verifies: tests ran, the linter passed, the change matches the reference.

What to leave out

• Things the code already says. The agent can read your package.json and folder structure.

• Personal preferences. Tone, verbosity, editor habits: those belong in each developer's own ~/.claude/CLAUDE.md, not the shared file.

• Rules for one folder. Put them in a CLAUDE.md inside that folder. Claude Code picks it up when working there, and the root file stays readable.

• Long prose. If a section needs paragraphs, it's documentation. Link to it instead of pasting it.

Keeping it true

A team CLAUDE.md fails quietly: it says one thing, the codebase moved on, and the agent confidently follows the old rule. Two habits prevent that:

1. Review it like code. Changes go through PRs, and any PR that changes a convention updates the file in the same PR.

2. Treat a bad agent suggestion as a bug report against the file. If the agent got something wrong because the rule was missing or stale, fix the file, not just the code.

Starting from your team's docs instead

Most of what goes into this template already exists somewhere in your team's documents: the onboarding guide, the engineering handbook, the page about who owns what. Turning that prose into short rules is the slow part.

That's 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 team-level files in 15 to 30 seconds. There's a free trial workspace, no card required.

Either way, start small: commands, one reference implementation, and the three rules your team breaks most often. That alone changes how Claude Code behaves in your repo.

The model is not the problem. Context is. Claude Code knows nothing about your team unless you write it down, and the place you write it down is a file called CLAUDE.md.

This guide covers what goes in that file when a team shares it, not just one person, and the mistakes that make it stop working after a month.

What CLAUDE.md actually does

Claude Code reads CLAUDE.md automatically at the start of every session. You do not paste it, reference it, or remind the agent. If the file is in your project root, it is in context.

There are three places it can live:

For a team, the repo-level file is the one that matters. It is checked in, reviewed like code, and every developer's agent reads the same rules.

If you have never made one, run /init inside Claude Code. It scans the repo and writes a starter file. That starter covers the code. It does not cover the team, and that is the part you need to add.

The five sections a team CLAUDE.md needs

1. Who owns what

The agent cannot ask "who reviews payments code?" unless the answer is in the file.

## Ownership
| Area | Owner | Reviews required |
|---|---|---|
| payments/ | Payments team | 2, one from payments |
| api/ | Platform team | 1 |
| web/ | Frontend team | 1 |

This alone stops a whole class of bad suggestions, like refactoring a module across a team boundary in one PR.

2. How decisions escalate

Write down what the agent should do when a task crosses a line: stop and ask, open an issue, or proceed.

## Escalation
- Schema changes: never apply directly. Write the migration, open a PR, tag the platform team.
- Anything touching billing: stop and ask before writing code.
- Dependency upgrades: allowed for patch versions only.

Short imperatives work better than prose. The agent follows "never apply directly" far more reliably than "we generally prefer that schema changes go through review."

3. The exact commands

List the build, test, and lint commands character for character. If you do not, the agent invents plausible ones, and plausible is not the same as correct.

## Commands
- Install: `pnpm install`
- Test one package: `pnpm --filter <pkg> test`
- Lint: `pnpm lint` (must pass before any commit)
- Never run: `pnpm db:reset` (wipes the shared dev database)

That last line has saved more than one team a bad afternoon.

4. What "good" means here

Every team has standards that are obvious to them and invisible to an outsider. Write the number down.

## Standards
- Test coverage on new code: 80% minimum
- API responses: p95 under 300 ms
- No new `any` types in TypeScript
- Commit messages: Conventional Commits (feat:, fix:, chore:)

5. The tools and systems

Which issue tracker, which CI, where logs live, which environments exist. The agent will reference these when it explains what to do next, so they should be real.

Per-role profiles: when one file is not enough

A single CLAUDE.md works until your team has people who need different defaults. A tech lead wants the agent to flag architectural risk. A new joiner wants it to explain conventions. A PM wants it to stay out of the code entirely.

A pattern that works well: keep the shared rules in CLAUDE.md, and add a short profile per role that someone loads when they start a session.

profiles/
  tech-lead/profile.md
  backend-engineer/profile.md
  product-manager/profile.md

Each profile covers how that role thinks, what they prioritize, and what they never compromise on. The shared file stays short. The profiles carry the difference.

Four mistakes that make it stop working

It grows until nobody reads it. Past a few screens, the important rules get lost among the trivia. If a section only matters for one folder, move it into that folder's CLAUDE.md.

It describes, instead of instructing. "Our team values clean code" changes nothing. "Functions over 40 lines need a comment explaining why" does.

It drifts from reality. The file says the tests run with Jest. The repo moved to Vitest in March. Now the agent is confidently wrong. Review the file when you review the code it describes.

It is written once by one person. The best CLAUDE.md files are edited by everyone who catches the agent getting something wrong. Treat a bad agent suggestion as a bug report against the file.

A faster way to write the first version

Most of what goes into a team CLAUDE.md already exists somewhere: an onboarding doc, an engineering handbook, a Notion page about who owns what. The slow part is turning that prose into short, enforceable rules.

That is the problem we built AI Workspace Builder to solve. You upload the docs your team already has (PDFs, markdown, Word files, or a Notion page), and it pulls out roles, processes, metrics, tools, and escalation paths, then generates the CLAUDE.md, a profile per role, and team-level files. It takes 15 to 30 seconds, and the free tier gives you one trial workspace with no card required.

Whether you use it or write the file by hand, the principle is the same: the agent is only as good as what you tell it about your team. Write it down once, keep it short, and keep it true.

What is the one rule in your CLAUDE.md that made the biggest difference? Drop it in the comments.