Claude Code Team Rollout: An Adoption Playbook That Works

The first rollout I watched consisted of a message in a channel with an install command and a link to the docs. Three weeks later about a fifth of the team was using it, most of them without any of the project configuration, and one person had quietly wired up an MCP server nobody had reviewed. Nothing had gone wrong exactly. Nothing had been decided either.

The lesson was that adoption is mostly a distribution problem. This post is the playbook I would use now: establish a baseline you can measure, ship configuration rather than instructions, place CLAUDE.md deliberately at three levels, separate policy from guidance, make installation trivial, teach the paradigm rather than the command list, and review what actually happened after a month.

Start with a baseline you can measure

Decide before you launch how you will know whether this worked, because after launch everyone has an anecdote and nobody has a number. On Team and Enterprise plans there is an analytics dashboard, and Enterprise adds an API so you can pull the data into whatever you already use. Contribution metrics need a claude.ai Team or Enterprise organisation and are opt-in.

If you deploy through a cloud provider instead, the analytics dashboard is not available, and OpenTelemetry metrics are your route — they work on every provider. Either way, pick two or three measures you would act on rather than a page of charts nobody reads, and write down what number would make you expand the rollout and what number would make you stop.

Ship configuration, not instructions

Anything a developer has to type is something most developers will not have. Put the marketplace and the plugins in the project's committed settings so they arrive with the repository once the folder is trusted, and have one central team configure the MCP servers in a committed configuration file rather than asking everyone to set them up.

// .claude/settings.json — committed, arrives with the repo
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "typescript-lsp@claude-plugins-official": true }
}

// .mcp.json — one central team configures it, everyone benefits
{
  "mcpServers": { "sentry": { "…": "…" } }
}

# Organisation-wide CLAUDE.md, deployed by MDM or Group Policy:
#   macOS         /Library/Application Support/ClaudeCode/CLAUDE.md
#   Linux, WSL    /etc/claude-code/CLAUDE.md
#   Windows       C:\Program Files\ClaudeCode\CLAUDE.md
# Or put the content straight into managed-settings.json:
{ "claudeMd": "Always run make lint before committing." }

Three places CLAUDE.md lives, and what belongs in each

Organisation-wide instructions go in a managed policy file deployed by your device management tooling, or directly into managed settings as a content key. Project instructions belong in the repository, checked in, describing architecture and build commands. Personal preferences belong in each developer's own file. The load order runs broadest to most specific, so a project instruction is read after an organisation one.

Separate policy from guidance

This is the distinction that saves the most argument later. Managed settings are enforced by the client regardless of what Claude decides; a managed CLAUDE.md shapes behaviour but is not an enforcement layer. Putting a hard requirement in prose is the most common rollout mistake, and it fails silently.

Where each concern belongs:

// managed-settings.json — enforcement, not advice
{
  "permissions": { "deny": ["Bash(curl:*)", "Read(./.env)"] },
  "sandbox": { "enabled": true },
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": "…",
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme/*" }
  ]
}

# If you ALSO use server-managed settings, put the login keys in
# BOTH places: managed sources do not merge, and the cached
# server-managed file replaces the device-managed one.
#
# Server-managed settings only reach accounts already signed in to
# your organisation — so they cannot redirect a first login.

Make installation one step

If your organisation has a custom development environment, a one-click way to install Claude Code is one of the highest-leverage things you can build for adoption. Every extra manual step is a place where a fraction of the team stops, and the ones who stop are rarely the ones who tell you. Bundle the install with whatever already provisions a developer machine.

Teach the paradigm, not the command list

The documented advice here matches what I have seen work: start people on codebase questions and small fixes rather than large autonomous tasks. Three things are worth saying explicitly in whatever onboarding note you write:

• Ask Claude to make a plan first, review it, and correct it when it is off track — that habit transfers to every harder task later.
• Expect to give feedback rather than accept output. The people who get the most from this are the ones who treat it as a colleague to redirect, not a generator to grade.
• Let people move to more agentic use at their own pace. Trying to start everyone on long autonomous runs produces exactly the bad first impression you are trying to avoid.

Review after a month

Come back to the numbers you chose, and to two things the tooling will tell you. Ask what plugins people installed and stopped using, because those cost startup time and context for no benefit. And read the CLAUDE.md files that have grown, because a file that doubled in a month is usually accumulating things that belong in a skill or a path-scoped rule instead.

The rollout that works is the one where a developer clones a repository, runs one command, and already has the marketplace, the plugins, the MCP servers and the project instructions. Everything else — the training note, the channel announcement, the office hours — helps at the margin. What determines adoption is whether the correct setup is the default, and that is a decision you make in configuration rather than in a message.