Claude Code Managed Policy: research and a public repo

Sergey Golubev 2026-04-22 7 min read
claude-code enterprise managed-policy mdm research open-source
🌐 Читать на русском

Cutaway illustration of a two-level office. On the upper floor, four IT administrators stand by a large control panel with rows of toggles and indicators; glowing labels above the panels read PERMISSIONS, MCP, MODELS, HOOKS. A translucent glass floor etched with MANAGED POLICY separates the levels. Below, an open workspace: seven developers at laptops running Claude Code. Thin glowing lines descend from the panel to each laptop, visualizing the flow of rules. Cold blue tones above, warm amber light below.

At an AI-IDE class I was asked about the top layer of Claude Code settings. The one configured by the company’s IT team that end users cannot override.

Hadn’t worked with it myself (I’m on a personal CC license), so I ran a separate research pass.

Published the output as an open repo: github.com/Serg1kk/claude-code-managed-policy.

Below is what surfaced. Target audience: anyone about to roll out Claude Code on a team of 10+ people.

What community guides usually say

Google “Claude Code managed policy” and most material boils down to a single file. Managed CLAUDE.md. A markdown file with behavioral instructions that IT drops into a system directory. Users cannot exclude it, and the model reads it every session.

Sounds clear. But it is not enough for real enterprise.

Actually two files — and the primary one gets skipped

Managed policy in Claude Code is two files with different jobs. If you only know about one, you are seeing less than half of the controls.

managed-settings.json - primary, hard enforcement. A JSON file the client reads at the start of every session. This is where the real controls live: permissions (what is allowed and denied, down to specific bash commands), model allowlist (restrict everything except Anthropic = BYOK blocking), MCP allow/deny, hooks, sandbox, mandatory login method. The model cannot physically reach a denied tool. This is not “instructions the model might ignore”, it is enforcement at the client level.

About 95% of compliance requirements are solved right here.

Managed CLAUDE.md - secondary, behavioral. The one everyone writes about. Behavioral instructions: tone, coding standards, company context. Injected into every session’s context as a user-message.

Key nuance, quote from AI Dev Conf (Maksim Etikhlid, tech lead): CLAUDE.md is injected as user-context, not into the system prompt. The model can ignore it, especially when the context is overloaded. For critical requirements, CLAUDE.md alone is unreliable. You need hooks plus permissions inside managed-settings.json.

Three delivery mechanisms, not just MDM

Community guides usually talk about one: MDM. In reality there are three, and at the managed tier they are mutually exclusive.

A. MDM / OS-level policies. The classic path. Jamf Pro, Kandji, Microsoft Intune, Group Policy. Anthropic publishes official starter templates for all four platforms. Linux is community-guides only (Ansible / Puppet / Chef).

B. Drop-in directory managed-settings.d/. Landed in v2.1.83, rarely covered. Modular policy composition. Files with numeric prefixes (10-security.json, 20-devops.json, 30-compliance.json) merge in systemd style. Different teams (InfoSec, DevOps, Compliance) can each ship their own slice independently. No need to co-author a monolithic JSON.

C. Server-managed settings. Launched in Q4 2025. No MDM required. The admin configures policy in the Claude.ai admin console, and the backend pushes it to the client on login. Works on BYOD and unmanaged devices. Unique among AI tools: Cursor, Copilot, and Codex all require device management for org-level enforcement. Minimum versions: Teams v2.1.38+ or Enterprise v2.1.30+.

Bypass: what works, what does not

Can a user just ignore the policy?

Short answer: not from the client. Long answer:

  • claude --setting-source local does not disable managed policy. Direct Anthropic quote from issue #11872: “Enterprise policies are not intended to be overridable.” Closed as by-design in December 2025.
  • --dangerously-skip-permissions is killed via managed disableBypassPermissionsMode: "disable".
  • Env vars and user-level claudeMdExcludes do not apply to managed CLAUDE.md.

The one remaining gap: .claude/rules/*.md (project-level modular rules). A user can exclude them via claudeMdExcludes in their own settings. The feature request claudeMdRequires (issue #34349) is open but not implemented yet. Workaround: put mandatory rules into the monolithic managed CLAUDE.md, and keep modular rules for guidance rather than enforcement.

Three concrete mismatches with community material.

Windows canonical path. Nearly everywhere you will see C:\ProgramData\ClaudeCode\. As of v2.1.75 that path is deprecated. The canonical path is now C:\Program Files\ClaudeCode\. Confirmed by the official docs: “The legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json is no longer supported as of v2.1.75.” Community mirrors like claude.yourdocs.dev still show the old one.

Linux canonical path. Some sources say /etc/claude/; the correct path is /etc/claude-code/ with a hyphen.

Two env vars floating around community forks. CLAUDE_MANAGED_SETTINGS_PATH and CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 appear in mintlify-style documentation mirrors. They are not in Anthropic’s official v2.1.x docs. Could be legacy, could be community myth. I flagged them as unverified and did not bake them into the template. Test in your own environment before relying on them.

When this actually matters

Any team rolling out Claude Code runs into one of four questions from different stakeholders. The managed policy surface answers them concretely:

  • Security: “How do we block BYOK and force corporate accounts only?” → forceLoginMethod + forceLoginOrgUUID.
  • DevOps: “How do we deploy this to 60 developers in one move?” → any of the three mechanisms above.
  • Compliance: “What gets logged when someone tries to run a denied command?” → Compliance API (Enterprise plan) + managed hooks.
  • Developer: “Can we work around this?” → three concrete answers in the bypass section.

If the topic is already on the table, a compact reference saves a week of ping-pong between teams.

Collected everything into an open repo

→ github.com/Serg1kk/claude-code-managed-policy

Inside:

  • 10 research files by section: paths, MDM, enforceable keys, bypass, use-cases, comparison with Cursor / Copilot / Codex / Windsurf
  • A ready-to-adapt managed-settings.json template for a 60-developer fintech team
  • A Managed CLAUDE.md behavioral template
  • An IT rollout checklist
  • README in two languages (EN default, with an RU toggle at the top)
  • Links to all 21 sources: official docs, GitHub issues, community guides

Fork it, adapt it, PRs for errors are welcome.

On process

Ran the topic through my own base first: processed YouTube analyses, KB of AI tooling notes, Telegram channel exports. Managed policy barely shows up there — it is a narrow enterprise topic that indie-developer YouTubers do not touch. From there: 10 Exa queries against Anthropic’s official docs, GitHub issues, and community guides; two agents on fact-check and cleanup passes; a couple of hours of editing. End state: a finished package and a public repo.

If you work at a company where rolling out Claude Code is already on the table and managed policy came up, the repo has everything you need. If it has not surfaced yet, you now know where to look when it does.

Sources

Other posts

All posts →

Skills as Apps 2.0: Replacing the SaaS Stack

In six months, skills turned a single Claude chat into my personal app store. How to replace SaaS with your own skills, and why it works beyond developers.

2026-05-10

Harness Engineering: the wrapper matters more than the model in 2026

Why 76% of AI agent tasks fail on the first try - not because of the model, but because of the harness - and what I keep in my stack.

2026-04-18