Enterprise Rollout

Rolling out agent coding to ten developers is easy: everyone installs, everyone experiments. Rolling it out to three hundred is different. Licenses, auth, governance, training, metrics, compliance — and the small but real risk that an underexposed developer runs the agent with no guardrails and leaks something.

This page covers the phased rollout pattern that works, the managed settings mechanism that backs it, and the metrics that tell you whether it is working.

Governance first, install second

Before anyone runs claude, answer:

Who authenticates how? Personal Claude Pro / Max, Claude for Teams, Claude for Enterprise SSO, Bedrock, Vertex, Microsoft Foundry. Pick one path and document it.
What are the hard limits? Which files are off-limits? Which commands (curl, wget, git push --force)? Which directories are production (infra/prod/**)?
Who writes the rules? Platform / DevX team owns managed-settings.json. Individual teams own .claude/settings.json in their repos.
What happens if something goes wrong? Incident process, rollback, responsibility.
What metrics do you track? See the end of this page.

If you cannot answer these in writing, you are not ready for 300 users.

Authentication options

Option	Best for	Trade-off
Claude for Enterprise	Mid and large orgs	SSO, domain capture, role-based permissions, managed policy settings, compliance API
Claude for Teams	Smaller teams (< 50)	Self-serve, admin dashboard, shared billing, no SSO enforcement
Claude Console	API-billed orgs	Per-user API keys via Console, optional SSO
Amazon Bedrock / Vertex AI / Microsoft Foundry	Orgs with existing cloud commit	Uses cloud provider credentials; data stays in your cloud

For CI and scripts, generate a long-lived OAuth token with claude setup-token and set CLAUDE_CODE_OAUTH_TOKEN in the environment.

Managed settings

Managed settings is the enforcement mechanism. It sits above every other settings layer — user, project, and CLI overrides cannot weaken it.

File-based delivery (most common):

macOS: /Library/Application Support/ClaudeCode/managed-settings.json
Linux / WSL: /etc/claude-code/managed-settings.json
Windows: C:\Program Files\ClaudeCode\managed-settings.json

There is also a drop-in directory alongside each of those paths, managed-settings.d/, where independent teams can drop policy fragments. Files merge alphabetically — use numeric prefixes (10-telemetry.json, 20-security.json) to control order.

Other delivery options:

Server-managed settings from the Claude.ai admin console (Enterprise only).
macOS MDM via com.anthropic.claudecode preferences domain (Jamf, Kandji, Intune).
Windows Group Policy / Intune via HKLM\SOFTWARE\Policies\ClaudeCode.

A baseline managed policy

The following is a reasonable starting point. Adjust to your environment — don't copy-paste blind.

{
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": "YOUR-ORG-UUID",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(git push --force*)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": false,
  "sandbox": {
    "enabled": true
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to agent coding at Acme — read the internal guide: docs.acme.com/ai"
  ]
}

Key settings worth knowing:

forceLoginMethod + forceLoginOrgUUID — lock users to your org.
allowManagedPermissionRulesOnly — when true, only rules in managed settings apply; project and user allow lists are ignored.
disableBypassPermissionsMode — prevents anyone from running with all permission prompts off.
sandbox.enabled — forces sandboxed Bash execution.
env — inject org-wide environment vars, including telemetry.
companyAnnouncements — cycled at session start. Good place to link to internal docs.
availableModels — restrict which models users can select.
blockedMarketplaces + strictKnownMarketplaces — lock down plugin sources.

A managed CLAUDE.md at the same path delivers org-wide behavioral guidance that developers cannot exclude.

The phased rollout

Phase 0: alignment (1 week). Sign off on the governance questions above. Pick the auth method. Decide which team owns managed settings.

Phase 1: platform team pilot (2 weeks). Ten to twenty people who already live in the terminal. Goals:

Validate the auth flow.
Build the initial managed-settings.json.
Write starter CLAUDE.md templates for two or three of your most common repo types.
Discover the hooks you actually need (lint gate, test gate, secret scanner).

Ship nothing to the wider org yet.

Phase 2: early adopters (4 weeks). Fifty to a hundred developers who opted in. Goals:

Stress-test the guardrails. What do they work around? What do they complain about?
Collect the "the agent did something weird" stories. Most will be CLAUDE.md gaps.
Write the internal guide: how to install, how to write a good prompt, how to use plan mode, how to debug when the agent does not follow instructions.
Set up telemetry dashboards.

Phase 3: broad rollout (ongoing). Open to everyone. Keep the following running:

A dedicated channel (Slack, Teams, whatever) for questions.
Weekly office hours with the platform team.
A shared list of known-good hooks and CLAUDE.md snippets.
An updated managed-settings.json as new risks surface.

Telemetry

Claude Code supports OpenTelemetry metrics. Set CLAUDE_CODE_ENABLE_TELEMETRY=1 and route to your OTLP collector. Useful signals:

Adoption. Active sessions per week, unique users.
Tool usage. Top 20 tool calls, ratio of Read vs Edit vs Bash, MCP server usage.
Blocks. How often hooks fire exit 2. How often permission denies hit. What commands get blocked.
Context use. Session length, compactions per session, context size at end.
Model mix. Opus vs Sonnet vs Haiku. Cost trendline.
Errors and retries. system/api_retry events, reasons.

Watch for: hooks that fire too often (either the rule is wrong or developers are fighting it), sharp Opus cost spikes, blocked commands trending up in one team (that team needs training or different rules).

Training, not just docs

A twenty-page wiki is less effective than a one-hour internal talk. The talk should cover:

The mental model shift (see Getting Started).
Writing a good prompt vs a vague prompt.
Using plan mode before big changes.
How to read the permission prompt and when to say no.
How to escalate when the agent does something weird.

Record it. Re-run it quarterly.

Compliance and audit

For regulated environments:

cleanupPeriodDays controls session log retention.
allowedHttpHookUrls restricts where HTTP hooks can send data.
sandbox.network.allowManagedDomainsOnly: true forces WebFetch through an admin-controlled allowlist.
OpenTelemetry logs every tool use, model call, and retry — plug into your SIEM.
ConfigChange hook fires when settings are modified mid-session; use it to audit or block drift.

Common mistakes orgs make

Shipping without managed settings. Everyone runs with bypassPermissions and the first incident is a CV-shaped hole in someone's week.
Writing managed settings too tightly. If developers can't do their normal work, they will work around you — alt accounts, shadow installs, VMs.
No CLAUDE.md templates. Every team writes a bad one and the agent behaves badly across the org.
No feedback channel. Developers hit the same problems twice. You never hear about them.
Rolling out to 300 people in one day. Always phase.

Enterprise Rollout