Enterprise Rollout

## 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:

1. **Who authenticates how?** Personal Claude Pro / Max, Claude for Teams, Claude for Enterprise SSO, Bedrock, Vertex, Microsoft Foundry. Pick one path and document it.

2. **What are the hard limits?** Which files are off-limits? Which commands (`curl`, `wget`, `git push --force`)? Which directories are production (`infra/prod/**`)?

3. **Who writes the rules?** Platform / DevX team owns `managed-settings.json`. Individual teams own `.claude/settings.json` in their repos.

4. **What happens if something goes wrong?** Incident process, rollback, responsibility.

5. **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.

```json

{

  "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](/s/agents-development/wiki/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

1. **Shipping without managed settings.** Everyone runs with `bypassPermissions` and the first incident is a CV-shaped hole in someone's week.

2. **Writing managed settings too tightly.** If developers can't do their normal work, they will work around you — alt accounts, shadow installs, VMs.

3. **No CLAUDE.md templates.** Every team writes a bad one and the agent behaves badly across the org.

4. **No feedback channel.** Developers hit the same problems twice. You never hear about them.

5. **Rolling out to 300 people in one day.** Always phase.

---

## Sources

- [Claude Code settings reference](https://code.claude.com/docs/en/settings)

- [Permissions and managed-only settings](https://code.claude.com/docs/en/permissions)

- [Authentication options](https://code.claude.com/docs/en/authentication)

- [Memory and managed CLAUDE.md](https://code.claude.com/docs/en/memory)

- [OpenTelemetry monitoring](https://code.claude.com/docs/en/monitoring-usage)

- [MDM starter templates](https://github.com/anthropics/claude-code/tree/main/examples/mdm)