Short answers to what readers ask most about this topic.
Rolling Claude Code out to a team is a configuration problem, not a training one. Here is what to ship, what to enforce, and what to measure.
Matthews Wong
Software Engineer
Key Takeaway
A Claude Code rollout succeeds or fails on what arrives automatically. Ship the marketplace, plugins and MCP servers through committed settings, put enforcement in managed settings and guidance in a managed CLAUDE.md, make installation one step, and measure adoption rather than announcing it.
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.
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.
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." }One committed MCP configuration file is worth more than any amount of documentation. It is the difference between every engineer having the same connection to your issue tracker and error monitor, and half of them having none while two have slightly different versions. Review it like any other shared infrastructure, because that is what it is.
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.
Keep the organisation-wide file short. It is loaded into the context window of every session, in every repository, for every developer on the machine — and unlike other CLAUDE.md files, individual settings cannot exclude it. That is exactly what you want for a compliance reminder and exactly what you do not want for two hundred lines of general advice, which costs everyone context and reduces adherence to the parts that matter.
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:
| Concern | Where it goes |
|---|---|
| Blocking tools, commands or file paths | Managed settings, as deny rules. Enforced by the client, not by persuasion |
| Sandbox isolation and provider routing | Managed settings, as the sandbox and environment blocks |
| Login method and organisation restriction | Managed settings. Note the two keys behave differently across login paths, and some paths enforce only one of them |
| Code style, conventions, compliance reminders | A managed CLAUDE.md. This is guidance, and it works well as guidance |
// 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.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.
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:
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.
Two configuration details will bite you if you skip them. If you use both device-managed and server-managed settings, put the login keys in both places — those sources do not merge, and the cached server-managed file replaces the device-managed one. And remember that server-managed settings only reach accounts already signed in to your organisation, so they cannot redirect anyone's first login.
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.
Sources & further reading