Claude Lessons / Guides

Claude Code for Teams: Rollout, Permissions, and Shared Config

Claude Lessons team · Updated August 7, 2026

Handing five engineers a Claude Code license and calling it a rollout produces five incompatible habits, not one team workflow. The parts that actually make Claude Code work across a team aren't about the product tier — they're a shared CLAUDE.md, settings that apply the same rules to everyone, and a rollout order that builds real conventions before expanding. This guide covers all three, plus the permission and governance settings that matter once more than one person's credentials are in play.

Why team rollouts fail

The common failure mode isn't a technical one — it's that Claude Code gets installed like an editor plugin, with no shared conventions, so every developer reinvents CLAUDE.md, permission settings, and prompting habits independently. Six months later, one person's sessions are fast and reliable, another's are fighting the model constantly, and nobody can tell why, because nothing about the setup is shared. Teams that get real leverage from Claude Code treat the first few weeks as building shared infrastructure, not distributing a tool.

A shared CLAUDE.md at the project root

One committed CLAUDE.md file is the highest-leverage thing a team can do, and it should exist before a broad rollout, not after. It's the same file described in our full CLAUDE.md best practices guide — stack, commands, conventions, no-touch zones — except now it's doing double duty as team documentation. New hires and new-to-Claude-Code teammates get the same "house style" from turn one instead of learning it by trial and error.

Build it with a small group first, not by committee:

• Pick 3-5 people already comfortable with the basics.
• Have them draft CLAUDE.md against the real repo, revise it after a week of real use.
• Only then commit it as the team default and expand access.

Shared MCP servers via .mcp.json

If the team relies on the same external tools — an issue tracker, a shared database, an internal API — configure those as project-scoped MCP servers and commit .mcp.json, covered in depth in our MCP guide. Every teammate who clones the repo gets the same tool access automatically, with a one-time approval prompt the first time — a safeguard, not friction to route around.

{
  "mcpServers": {
    "linear": { "type": "http", "url": "https://mcp.linear.app/mcp" },
    "internal-api": { "type": "stdio", "command": "node", "args": ["./tools/mcp-server.js"] }
  }
}

Keep personal-only servers (a developer's own scratch tools) at local or user scope so they don't leak into the shared config.

The settings hierarchy: who wins

Claude Code settings are layered, and the more specific / more locked-down layer wins:

Put team-wide rules — required hooks, allowed/denied tool patterns, model defaults — in the committed .claude/settings.json. Personal preferences (your own notification sound, a personal alias) belong in user or local-project settings so they don't churn the shared file.

Permission modes: what a team should default to

The mistake teams make in the other direction is defaulting to bypass mode to "move fast," then discovering it applies the same way to a stray rm -rf as it does to a routine edit. See our security best practices guide for the fuller picture on permissions, secrets, and sandboxing.

A phased rollout that actually works

The order matters more than the timeline — a team that skips straight to phase 3 spends months converging on conventions that a five-person pilot could have settled in two weeks.

Governance: hooks and managed policy

Once more than one person's credentials are involved, rules that live only in CLAUDE.md prose aren't enough — see our hooks guide for the enforcement layer. A PreToolUse hook committed to .claude/settings.json that blocks force pushes or writes to .env applies to every developer who uses the repo, regardless of their personal settings — that's the difference between a rule people are asked to follow and one they can't bypass by accident.

For org-wide requirements that shouldn't be editable by individual developers at all — model access, network restrictions, tool allow-lists — enterprise managed settings, deployed centrally by an admin, sit above every other layer.

Common mistakes

• No shared CLAUDE.md before broad rollout. Everyone ends up teaching Claude Code the same conventions individually, badly.
• Defaulting to bypassPermissions for speed. Fine in a disposable container, dangerous on a laptop with real credentials — see the security guide.
• Treating .mcp.json as personal config. Uncommitted, it means half the team has tool access the other half doesn't, for no reason.
• Skipping the pilot phase. Rolling out to fifty developers before conventions exist multiplies the chaos of an ungoverned setup by fifty.
• Putting enforcement-grade rules only in CLAUDE.md. A written rule is a request; anything the team truly can't afford to skip needs a hook, not just a sentence.

FAQ

What's the difference between local, project, and user settings in Claude Code?

User settings (~/.claude/settings.json) apply to you across every project. Project settings (.claude/settings.json) are committed to the repo and shared with the team. Local project settings (.claude/settings.local.json) are yours only, for this project, and meant to be gitignored. Enterprise-managed settings, deployed by an admin, override all of them.

Should a team commit CLAUDE.md and .mcp.json to git?

Yes, for both. CLAUDE.md at the project root should be committed so every teammate's Claude Code session gets the same conventions, and .mcp.json (project-scoped MCP servers) should be committed so the team shares the same tool access. Anyone who clones the repo gets a one-time approval prompt before a committed .mcp.json's servers activate, which is a deliberate safeguard, not a bug.

What permission mode should a team default to?

For most teams, the default interactive permission mode (approve each new tool/command category) or acceptEdits (auto-approve file edits, still prompt for commands) is the right starting point — not bypassPermissions. Reserve bypass modes for sandboxed environments like CI or disposable containers, never for a session with access to real credentials or production systems.

How do you roll out Claude Code to a whole engineering team without chaos?

Phase it. Start with a small group building the shared CLAUDE.md and documenting which tasks work well, run an internal session sharing what they learned, then expand — pairing less experienced adopters with people who've already built the habits. A team-wide rollout with no shared conventions produces a dozen incompatible individual workflows instead of one team habit.

Can an org enforce security rules across every developer's Claude Code?

Yes, through managed settings deployed by an admin (outside any individual developer's control) plus hooks committed to the shared .claude/settings.json — a PreToolUse hook that blocks force pushes or writes to .env applies to everyone who uses the repo, regardless of their personal settings.