Onboarding a Team to Claude Code

Claude code team onboarding usually fails for a boring reason: one engineer gets great results, tells the team to "just try it," and everyone else opens it once, gets a permission prompt they don't understand, and closes the terminal. Rolling out Claude Code to a team is not a tooling problem, it's a setup and habits problem. This guide walks through a rollout that gets past the first-hour drop-off: install and auth, a shared CLAUDE.md, permission and settings defaults, a plugin/skill strategy, and the workflows that make the tool worth keeping open.

Why claude code team onboarding needs a plan, not just an install link

Claude Code is a terminal-based coding agent: you run it inside a repo, it reads files, edits code, runs shell commands, and can call out to MCP servers for things like browsers, databases, or issue trackers. That power is exactly why an ungoverned rollout goes sideways. A new user who hasn't seen the permission system will either approve everything out of impatience (dangerous) or reject everything out of caution (useless). A team that hasn't agreed on a shared CLAUDE.md will end up with five engineers each re-explaining the build system to the agent in their own session, every day.

The fix is to treat onboarding like you would onboarding a new hire: give them a written map of the repo, a known-good config, and a first task that is guaranteed to work. Do that and most engineers are productive with Claude Code inside a single sitting.

Step 1: install and authenticate before the team meeting

Send this before the kickoff, not during it, so the meeting is spent on workflows, not npm errors.

npm install -g @anthropic-ai/claude-code
claude --version

Authentication is either an Anthropic Console API key (billed per token, good for teams that want centralized cost control) or a Claude subscription login (flat monthly cost, good for smaller teams or solo trials). Decide this at the org level before onboarding starts, because switching auth methods mid-rollout means everyone re-authenticates.

For a company-wide rollout, use environment-level configuration so individual engineers don't have to set anything manually:

export ANTHROPIC_API_KEY="sk-ant-..."

If you're on a Claude subscription instead of API billing, just run claude in a terminal and follow the browser login flow. Either way, confirm the install with a no-op:

claude -p "reply with the word ready"

If that returns cleanly, the person is authenticated and unblocked. Do this check for every new hire in week one, the same way you'd check their VPN or git access.

Step 2: write the CLAUDE.md before anyone touches the agent

This is the single highest-leverage step in claude code team onboarding, and the most skipped. CLAUDE.md is a plain markdown file at the repo root that Claude Code reads automatically at the start of every session. It is the onboarding doc you wish every new hire read, except the agent actually reads it every time, not once.

A CLAUDE.md that earns its keep has four sections, kept short:

# Repo map
What this repo does, in three sentences. Link to any sibling repos and explain
what each one owns, so the agent doesn't guess.

# Commands
- Dev server: `npm run dev` (port 3000)
- Tests: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

# Conventions
- State management: Zustand, not Redux
- API routes live in `src/server/routes/`, one file per resource
- Never touch `generated/` by hand, it's codegen output

# Guardrails
- Never commit directly to `main`
- Never run destructive db migrations without asking first
- Tests must pass before any commit

Keep it under a page. A CLAUDE.md that reads like a wiki gets skimmed, not followed. If the repo has sub-projects with their own conventions (a monorepo with a backend/ and frontend/), put a short root CLAUDE.md that points to nested CLAUDE.md files in each subdirectory. Claude Code picks up the nearest one automatically as it works in that part of the tree, so engineers working only on the frontend don't have to read backend-specific rules.

Commit this file into the repo. It is not personal config, it's team config, and it should go through the same PR review as anything else. When conventions change, the CLAUDE.md changes in the same PR.

Step 3: set permissions before day one, not after an incident

The default permission model asks before every file write, shell command, or tool call outside a small safe list. That's correct behavior for a brand-new user, but it makes the tool feel like a wall of "yes/no" prompts if nobody has configured sane defaults. The fix is a project-level settings file, checked into the repo, that pre-approves the commands your team runs fifty times a day without touching anything dangerous.

Create .claude/settings.json in the repo:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Read(**)"
    ],
    "deny": [
      "Bash(git push --force*)",
      "Bash(rm -rf*)",
      "Bash(git reset --hard*)"
    ]
  }
}

This does two things at once: it removes prompt fatigue for routine reads and test runs, and it puts a hard deny on the handful of commands that cause real damage (force pushes, hard resets, recursive deletes). Every engineer inherits this the moment they clone the repo and run Claude Code inside it, no personal setup required.

Keep personal preferences out of this file. If someone wants their own model default or a personal alias, that belongs in their user-level ~/.claude/settings.json or ~/.claude/CLAUDE.md, not the project one. Mixing personal and team config in the same file is the most common reason project settings drift out of sync with what the team actually agreed on.

Step 4: pick 3 to 5 workflows and write them down as skills

A common onboarding mistake is showing new users the raw tool and saying "ask it anything." That's true but not actionable. Engineers adopt tools fastest when they have a short list of named things it's good at, matched to work they already do every week.

For most teams that list looks like:

• Fix a failing test given a stack trace and a file path
• Write a first-pass PR description from a diff
• Investigate "where is X defined / what calls Y" across an unfamiliar part of the codebase
• Draft a migration or refactor plan before touching code
• Review a diff for correctness bugs before opening a PR

If any of these repeat often enough to have their own internal jargon (your team's specific PR template, your team's specific test-writing convention), turn it into a skill: a folder under .claude/skills/ with a SKILL.md that describes when to trigger it and what steps to follow. Skills are how a team encodes "this is how we do X here" so every engineer's agent behaves consistently instead of each person re-explaining the same process in every session.

A minimal skill for "write a PR description" looks like:

---
name: pr-description
description: Draft a PR description from the current diff, following our template
---

Read the diff against the base branch. Write a PR description with:
- A one-paragraph summary of what changed and why
- A bulleted list of user-facing changes, if any
- A "Test plan" checklist section
Do not restate the diff line by line. Do not use marketing language.

Ship this in the repo alongside CLAUDE.md. New engineers get it automatically; nobody has to remember to tell them it exists.

Step 5: run one guaranteed-win task in the onboarding session

Don't hand a new user an open-ended "explore the codebase" prompt on day one, it's a bad first impression because the output is diffuse and hard to judge. Instead, pick a task with a clear, checkable outcome:

claude "Find the function that handles password reset emails, and add a unit
test for the case where the email address doesn't exist in the database.
Run the test suite after to confirm it passes."

This works as a first task because it has a verifiable end state (test exists, test passes), it touches real code so the person sees the agent read files and reason about the codebase, and it's small enough to review in five minutes. Do this live in the onboarding session so the new engineer sees the permission prompts happen once, sees them get approved, and understands what each one means before they're on their own.

Step 6: decide how the team shares MCP servers

If your team uses MCP servers (a database client, an issue tracker, a browser automation tool), configure those at the project level too, not per-engineer. A .mcp.json at the repo root, checked into git, means every engineer who clones the repo and opens Claude Code gets the same tool access without hunting down connection strings or API keys in Slack history.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "$DATABASE_URL"]
    }
  }
}

Keep secrets out of this file, reference environment variables instead, and document in CLAUDE.md which env vars a new engineer needs to set before the MCP server will connect. This is the same discipline as any other local dev setup: the file that defines the connection is shared, the credentials are not.

Step 7: set expectations on review, not just usage

The last piece of claude code team onboarding is cultural, not technical: agent-written code goes through the same review bar as human-written code. Teams that skip this end up with two failure modes, either engineers rubber-stamp anything the agent produces because it "looks right," or engineers distrust the tool entirely after one bad diff slips through review. Neither is really about the tool.

State the rule explicitly during onboarding: every diff, agent-authored or not, gets read by the person who opened the PR before it's sent for review, and gets reviewed by a second person before merge. If your team already uses a review skill or checklist, point new engineers at it and make clear it applies here too. This single sentence prevents most of the post-rollout trust issues that show up a few weeks in.

FAQ

Do all engineers need the same authentication method? Not strictly, but it's easier to manage if they do. Centralized API billing gives you usage visibility per repo or per team; individual subscription logins are simpler to set up but harder to track spend against. Pick one at the org level before rollout so you're not mixing billing models mid-project.

Should CLAUDE.md live in the repo or somewhere personal? In the repo, always, for anything that describes how the team works. Personal preferences (a favorite model, a personal alias) belong in the engineer's own user-level config, not the project file. If it would go in an onboarding doc for a human hire, it belongs in the project CLAUDE.md.

What's the biggest reason team rollouts stall after week one? Permission fatigue. If every command triggers a prompt because nobody configured project-level .claude/settings.json, engineers quietly stop using the tool rather than fight the prompts. Fix the settings file before the second week, not after people have already given up.

How much of the codebase should the first onboarding task touch? As little as possible. A task that touches one function and one test file is enough to demonstrate the whole loop, read the codebase, write the change, run the check, report the result. Open-ended "refactor this module" tasks are a good week-two exercise, not a day-one one.

Do skills replace documentation? No. Skills encode workflows the agent should follow when a task matches a pattern; they're procedural, not reference material. Keep your architecture docs and API references where they already live, and use CLAUDE.md to point the agent at them when relevant, rather than duplicating that content inside a skill.

What's the fastest way to tell if onboarding actually worked? Look at usage two weeks out, not day one. If engineers are opening Claude Code for ad-hoc tasks without being told to, the rollout worked. If usage drops to zero after the kickoff session, go back to the permission settings and the CLAUDE.md, that's almost always where the friction is.