Claude Code Team Onboarding Guide: From Solo to Team Deployment in 2026

Rolling out Claude Code to a solo developer is straightforward. Rolling it out to a team of eight — or eighty — is a different problem. Teams fail at Claude Code adoption for reasons that have nothing to do with Claude’s capabilities: inconsistent CLAUDE.md files across repos, permission mode disagreements between developers, one team member who changes the shared configuration without telling anyone, and no clear ownership of the MCP servers that everyone depends on.

We reviewed Claude Code team setups across engineering teams ranging from 3 to 60 developers and identified the patterns that determine whether a rollout succeeds. The difference between a team where Claude Code becomes invisible infrastructure and one where it creates friction comes down to three things: who owns what, where configuration lives, and how personal overrides stay isolated from shared standards.

This guide covers claude code team setup from initial configuration through team-size-specific playbooks, with role-specific onboarding checklists for developers, tech leads, and engineering leads.

Why Team Claude Code Rollouts Fail (And How to Avoid It)

Most team rollouts fail at one of three points.

Failure 1: Uncontrolled CLAUDE.md drift. Someone adds project-specific rules to the shared CLAUDE.md. Someone else removes them “to keep it clean.” A third developer adds their personal style preferences to what was supposed to be a team standard. Within a month, the CLAUDE.md reflects the last person to edit it, not the team’s actual conventions.

Failure 2: Permission mode conflicts. One developer runs Claude in --dangerously-skip-permissions for speed. Another uses default interactive mode. The third has a custom settings.json that blocks file system access. The result is that no one can share the same workflows, and “it works on my machine” problems multiply.

Failure 3: MCP server sprawl. Each developer installs different MCP servers in their local configuration. The shared mcp.json gets stale. Someone removes a server that others depend on. There’s no source of truth for which MCP tools the team’s CLAUDE.md instructions reference.

The solution to all three is the same: define what’s shared, define what’s personal, and put them in different places.

Shared CLAUDE.md: What Belongs in Team Settings vs Personal Overrides

Claude Code loads CLAUDE.md files from three locations, in order of precedence:

1. User-level CLAUDE.md (~/.claude/CLAUDE.md)
2. Project root CLAUDE.md (committed to the repository)
3. Subdirectory CLAUDE.md files (loaded for context-relevant paths)

For teams, this hierarchy is the key to separating shared standards from personal preferences.

What Goes in the Committed CLAUDE.md (Team Standard)

The project-level CLAUDE.md belongs to the team, not to any individual. It should contain:

• Stack and toolchain: language versions, package managers, database engines
• Build and test commands: the exact commands that run in CI (not shortcuts that work locally)
• Code style decisions: formatter choice, import order, naming conventions
• Migration and schema rules: anything that can break production if done incorrectly
• Security guardrails: what Claude should never do (commit secrets, log credentials, eval() user input)
• Project-specific domain rules: soft-delete patterns, multi-tenancy scoping, auth conventions

What it should NOT contain:

• Personal editor preferences
• Local path configurations
• Individual developer’s workflow shortcuts
• Personal API key references

A useful test: if a developer who joined yesterday should follow this rule, it belongs in the committed CLAUDE.md. If it’s a preference that only makes sense for one person’s setup, it belongs in their personal override.

Personal Overrides: CLAUDE.md.local and User-Level Configuration

Claude Code supports project-level personal overrides via .claude/CLAUDE.md.local. This file is not committed to the repository (add it to .gitignore) and loads after the committed CLAUDE.md. Personal overrides should contain:

• Personal workflow shortcuts (just deploy-staging instead of the full command)
• Local path adjustments (if the developer has a non-standard directory structure)
• Personal preferences that don’t affect output correctness (verbosity level, response style)

Add .claude/CLAUDE.md.local to your repository’s .gitignore:

# .gitignore
.claude/CLAUDE.md.local
.claude/settings.local.json

The user-level ~/.claude/CLAUDE.md is another layer for preferences that apply across all of a developer’s projects — personal coding style preferences, preferred response format, and cross-project toolchain shortcuts.

Hierarchy Design for a Real Team

A team CLAUDE.md hierarchy that scales well looks like this:

~/.claude/CLAUDE.md              # Personal (not committed, user-owned)
  └─ Personal style, cross-project shortcuts

project/
  CLAUDE.md                      # Team standard (committed, team-owned)
    └─ Stack, commands, guardrails, conventions
  .claude/
    settings.json                # Team permission policy (committed)
    settings.local.json          # Personal permission overrides (gitignored)
    CLAUDE.md.local              # Personal project overrides (gitignored)
    rules/
      models.md                  # Path-scoped rules for models/
      api.md                     # Path-scoped rules for API layer
      tests.md                   # Path-scoped rules for test files

AGENTS.md for Cross-Tool Teams (Cursor + Claude Code in the Same Repo)

Teams that use multiple AI coding tools — Claude Code for terminal workflows, Cursor for editor-integrated work — need AGENTS.md in addition to CLAUDE.md.

AGENTS.md is read by Claude Code, Cursor, Codex CLI, Aider, Kiro, and other tools that follow the AGENTS.md specification. CLAUDE.md is read only by Claude Code. When your team uses multiple tools, AGENTS.md becomes the lingua franca for shared conventions.

Division of Labor Between AGENTS.md and CLAUDE.md

A practical pattern for cross-tool teams: keep AGENTS.md as the minimal shared standard, and use CLAUDE.md to reference AGENTS.md while adding Claude Code-specific instructions.

# CLAUDE.md

@AGENTS.md

## Claude Code-Specific Configuration

The AGENTS.md above contains shared conventions for all AI tools.
The following applies to Claude Code sessions only.

## Hooks

See .claude/settings.json for PostToolUse hooks (linting, type checking).

## Permission Policy

Default mode: plan mode for destructive operations (migrations, deletions).
See settings.json for the full permission configuration.

Permission Mode Policies for Different Team Roles

Claude Code’s permission model governs which tool calls require confirmation. The right configuration differs between developers doing exploratory work and production systems running in headless CI.

Recommended Permission Profiles by Role

Developers (interactive development):

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(python -m pytest *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)",
      "Read(**)",
      "Edit(**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Bash(kubectl delete *)",
      "Bash(terraform destroy *)"
    ]
  }
}

Tech Leads (wider access, infrastructure-aware):

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(python -m pytest *)",
      "Bash(git *)",
      "Bash(docker compose *)",
      "Read(**)",
      "Edit(**)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(terraform destroy -auto-approve *)",
      "Bash(kubectl delete namespace *)"
    ]
  }
}

CI/CD headless sessions:

{
  "permissions": {
    "allow": [
      "Bash(npm ci)",
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(python -m pytest)",
      "Read(src/**)",
      "Read(tests/**)"
    ],
    "deny": [
      "Bash(*)",
      "Edit(**)"
    ]
  }
}

The team-committed settings.json should contain the most conservative policy that covers day-to-day work. Developers who need wider access add it to their personal settings.local.json.

Plan Mode for Sensitive Operations

For operations that are hard to reverse — database migrations, infrastructure changes, bulk file edits across the repository — configure Claude Code to use plan mode. Plan mode requires explicit confirmation before execution.

Document this in your team CLAUDE.md:

## Operations Requiring Plan Mode Approval

Before executing the following, Claude will present a plan and wait for confirmation:

- Generating or running database migrations
- Any command targeting the production database
- Bulk file renames or moves (more than 5 files)
- Dependency version upgrades
- Anything involving `kubectl`, `terraform`, or `ansible`

MCP Server Configuration at Team Scale

MCP servers that individual developers install locally are invisible to their teammates. Team-scale MCP configuration requires a committed mcp.json that everyone loads, plus a process for proposing and adding new MCP servers.

Committed MCP Configuration

Claude Code loads MCP server configuration from .mcp.json at the project root. This is the right place for MCP servers that the team’s CLAUDE.md instructions depend on.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"],
      "env": {
        "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}"
      }
    }
  }
}

Environment variables in MCP configuration use ${VAR_NAME} syntax. The actual secrets are injected at runtime — either from the developer’s shell environment or from a secret manager via op run.

MCP Server Governance

Define a process for proposing new MCP servers before they get added to the shared configuration:

## Adding New MCP Servers (from team CLAUDE.md)

New MCP servers require review before being added to .mcp.json:
1. Propose the server in the team's engineering channel
2. Tech lead reviews the server's source and permissions
3. PR to .mcp.json requires two approvals
4. Document the server in the "MCP Tools" section of this CLAUDE.md

MCP servers for personal workflows belong in ~/.claude/mcp.json, not .mcp.json.

Onboarding Checklist by Role

Developer Onboarding Checklist

Day one checklist for a developer joining a team using Claude Code:

Environment setup:

• Install Claude Code: npm install -g @anthropic-ai/claude-code
• Authenticate: claude --auth (use company SSO if configured)
• Verify the committed CLAUDE.md loads: claude --print-claude-md
• Install MCP dependencies from .mcp.json: check README.md for required env vars
• Copy .env.example to .env and fill in local values
• Run claude in the project root and verify it finds CLAUDE.md

Configuration:

• Add .claude/CLAUDE.md.local to store personal shortcuts (already gitignored)
• Review .claude/settings.json to understand the team’s permission policy
• Add personal exceptions to .claude/settings.local.json if needed (gitignored)
• Verify ~/.claude/CLAUDE.md doesn’t conflict with the project standard

First session:

• Run claude and ask it to describe the project (verify CLAUDE.md is understood)
• Ask Claude to explain the migration policy (verify critical rules are loaded)
• Run the test suite through Claude and verify it uses the correct commands

Tech Lead Onboarding Checklist

When a tech lead joins or takes ownership of a team’s Claude Code setup:

Audit existing configuration:

• Review the committed CLAUDE.md for accuracy and completeness
• Check .claude/settings.json for permission policy gaps
• Review .mcp.json for stale or unnecessary servers
• Verify .gitignore excludes personal override files

Establish team standards:

• Define which operations require plan mode approval (document in CLAUDE.md)
• Set the MCP server governance process (who approves new servers)
• Create path-scoped rules in .claude/rules/ for domain-specific conventions
• Set up a team ~/.claude/CLAUDE.md template for new developer onboarding

Review cycle:

• Schedule a quarterly CLAUDE.md review (conventions change, the file should too)
• Set up CI validation: a linter or check that verifies CLAUDE.md exists and is non-empty
• Document the escalation path: what developers do when Claude behaves incorrectly

CTO / Engineering Lead Onboarding Checklist

For engineering leaders evaluating or rolling out Claude Code at the organization level:

Policy decisions:

• Define the permission policy baseline for your organization’s risk tolerance
• Determine which MCP servers are organization-approved vs. developer-discretionary
• Decide whether Claude Code usage in CI requires separate authentication
• Confirm the team is using Max subscription (for $100/month unlimited usage) or API billing

Security review:

• Audit .mcp.json for servers with broad file system or network access
• Verify secrets are injected via environment variables, not hardcoded in config
• Review the audit trail: Claude Code logs sessions to ~/.claude/projects/
• Determine data retention policy for session logs

Rollout sequencing:

• Start with one team as a pilot (2-4 developers, 4-6 weeks)
• Collect feedback on which CLAUDE.md rules produced the most value
• Use the pilot’s CLAUDE.md as the starting point for the org-wide template
• Define which teams adopt Claude Code first vs. which wait for the pilot results

Team Size Playbooks

1–5 Engineers

At this size, a single committed CLAUDE.md works. The team is small enough that everyone can discuss and agree on changes synchronously.

What to configure:

• One CLAUDE.md in the project root (300 lines maximum)
• One .mcp.json with shared MCP servers
• Personal overrides in CLAUDE.md.local (gitignored)

What to skip:

• Path-scoped rules in .claude/rules/ (overhead outweighs benefit at this size)
• Formal governance for CLAUDE.md changes (PRs with two approvals is enough)
• Separate permission profiles (one shared settings.json is fine)

Common mistake: Writing a CLAUDE.md that’s too long. At 1–5 engineers, you can talk to each other. The CLAUDE.md only needs to cover what Claude gets wrong, not everything you know about the codebase.

6–20 Engineers

At this size, CLAUDE.md starts to need structure. Multiple teams or work streams mean different parts of the codebase have different conventions.

What to configure:

• Root CLAUDE.md for cross-cutting standards (migration policy, security guardrails)
• Path-scoped rules in .claude/rules/ for domain-specific conventions
• A CLAUDE.md.local template in the repository’s docs/ for new developers to copy
• Two-approval PR requirement for changes to committed configuration

MCP governance:

• Designate one tech lead as the MCP server owner per repo
• MCP servers that access production systems require explicit approval
• Personal MCP tools stay in ~/.claude/mcp.json, not .mcp.json

Permission policy:

• Committed settings.json with the team’s baseline restrictions
• Document which operations require plan mode in the CLAUDE.md

Common mistake: Letting different teams maintain independent CLAUDE.md files that drift apart. At 6–20 engineers, the cost of duplication is high enough to warrant a shared template repository.

20+ Engineers

At this size, CLAUDE.md becomes organizational infrastructure. Changes affect many developers. Drift between teams creates inconsistency. The file needs versioning, review processes, and a clear owner.

What to configure:

• A shared CLAUDE.md template repository that individual project repos import or copy from
• Automated validation in CI that checks CLAUDE.md against the organizational template
• A CLAUDE.md owner (usually a senior tech lead or platform team) who approves changes
• Separate settings.json profiles for different team roles (developer, tech lead, CI)
• Documented MCP server inventory with security review status per server

AGENTS.md standardization:

• An org-wide AGENTS.md template that all repos start from
• Individual repos extend the org template rather than replacing it

Process:

• CLAUDE.md changes require an RFC or lightweight design doc for significant modifications
• New MCP servers require security review before org-wide adoption
• Quarterly audits to remove stale rules and update outdated command examples

Common mistake: Treating the 20+ playbook as necessary from day one. Invest in governance infrastructure only when the pain of inconsistency becomes measurable. Most teams hit that point between 10 and 20 developers.

FAQ

Who should “own” the team’s CLAUDE.md?

A tech lead or the person most familiar with the codebase’s conventions. The owner’s job is not to write everything themselves — it’s to review PRs that change the CLAUDE.md, resolve conflicts between developers’ preferences, and ensure the file reflects actual team practice rather than aspirational standards. Ownership should rotate or transfer when the lead changes.

What happens when two developers disagree about a CLAUDE.md rule?

Treat it like any other technical decision: discuss the trade-off, default to the more conservative option, and document the rationale. A rule that’s too strict can be relaxed. A rule that causes Claude to do something harmful is harder to recover from. When in doubt, make the rule a recommendation rather than an absolute: “prefer X” rather than “always X.”

Should CLAUDE.md be different per environment (dev vs staging vs prod)?

The committed CLAUDE.md should work correctly in all environments. Environment differences that affect behavior — different database URLs, different service endpoints — belong in environment variables, not in CLAUDE.md. If a rule only applies in production (e.g., “never run migrations against the production database without a backup”), include it in CLAUDE.md with explicit environment scope.

Can we use CLAUDE.md to enforce pair programming or review requirements?

Partially. CLAUDE.md can instruct Claude Code to always present a plan before executing migrations, to generate PR descriptions that include a testing checklist, or to flag changes that touch security-sensitive code. These are soft enforcements that Claude Code follows when it processes the instructions. Hard enforcement (e.g., blocking a push without a second approval) requires your CI configuration, not CLAUDE.md.

How do we handle CLAUDE.md for a monorepo with different stacks per package?

Use the hierarchy: a root CLAUDE.md for monorepo-wide conventions (commit format, changelog policy, shared tooling), and package-level CLAUDE.md files for stack-specific conventions. Path-scoped rules in .claude/rules/ are another option — rules that load only when files in packages/frontend/ are in context. See the monorepo patterns guide for detailed examples.

Should settings.json be committed or gitignored?

Commit the team baseline settings.json. Gitignore settings.local.json. The committed settings.json encodes the team’s agreed permission policy — the restrictions and allowed operations that apply to everyone. The personal settings.local.json allows individual developers to expand (or further restrict) permissions for their own use without affecting their teammates.

What’s the first thing to add to CLAUDE.md when onboarding a new team?

The test command and the linting command. These are the two most frequently used non-trivial commands that Claude Code needs to run correctly. If Claude runs the wrong test command, the feedback loop breaks. If it runs the wrong linter, it can’t self-correct style errors. Everything else — model conventions, security rules, workflow patterns — can be added incrementally as the team identifies gaps.

Related Articles

• CLAUDE.md Best Practices: 12 Patterns from 100+ Real Repos
• Claude Code settings.json Team Git Management
• AGENTS.md in Monorepos: Per-Package Instructions
• Browse team-ready AI coding rule templates in our gallery

Manage Secrets Across Your Whole Team

As teams scale, secrets management becomes critical. Developers shouldn’t share .env files over Slack, and CI systems shouldn’t store raw credentials in environment variables. 1Password CLI’s op run injects secrets at runtime from a shared vault — every developer gets the right credentials, every session is audited, and no secrets land in shell history or committed config files.