Developer Productivity & Operational Enablement · Lesson 1 of 3

7.1 - Configuring Claude Code and Environments for a Team

Decide which Claude Code mechanism (CLAUDE.md, rules, settings, hooks, skills, MCP, managed policy) belongs at which scope, and how to roll a team configuration out so that it is shared, enforced where it must be, and verifiable.

Team configuration is a placement problem. Every rule, tool or capability you want Claude Code to have for a team has two properties: who it reaches (its scope) and how hard it binds (its guarantee). Scenario questions almost always hinge on a mismatch between the two: a compliance rule left as advice, a personal preference committed for everyone, or a team convention that lives only on one developer's laptop.

Three different guarantees

Guidance. CLAUDE.md, .claude/rules/ and auto memory are loaded into the context window. The memory docs say Claude treats them as context, not enforced configuration, and that if two rules contradict each other Claude may pick one arbitrarily.
Enforcement. Permission rules, permission modes, sandboxing and hooks are applied by Claude Code itself, not decided by the model. A PreToolUse hook script that exits with code 2 blocks the tool call every time.
On-demand capability. Skills keep only their description in context until they are invoked; subagents work in their own context window; MCP servers add external tools.

Rule of thumb: “we do it this way here” goes in CLAUDE.md or a path-scoped rule; “this must never (or always) happen” goes in a permission rule, the sandbox or a hook; an occasional workflow goes in a skill.

Common exam distractor

Answers that say the “more specific” or “closer” CLAUDE.md wins, or that a CLAUDE.md line guarantees a rule, are wrong. Files are concatenated, ordered from broad to specific (a project file appears after a user file; files nearer your working directory are read last), and that is load order, not precedence. Only settings.json has a real precedence stack.

Placing instructions: scope decides who receives them

Scope	Location	Reaches
Managed policy	`/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux, WSL), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows)	Everyone in the organisation; cannot be excluded
User	`~/.claude/CLAUDE.md`	You, in every project; never travels through git
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`	The team, via source control
Local	`./CLAUDE.local.md` (gitignore it)	You, in this project

Files in the directory tree above your working directory load at launch; CLAUDE.md files in subdirectories load on demand, when Claude reads a file there. .claude/rules/*.md files without paths frontmatter load at launch; with paths they load when Claude reads matching files, which scopes a convention such as test style across many directories without a file in each.

Keep each file short (the docs target under 200 lines). @path imports aid organisation but still load at launch, so they save no context; in a monorepo, claudeMdExcludes skips other teams' files. To see what loaded, run /context and read the Memory files list; /memory lists and opens the files. Neither loads anything.

The new-teammate diagnosis

Developer A gets the team conventions; developer B, on the same repo and branch, does not. The conventions are almost certainly in A's ~/.claude/CLAUDE.md (or an untracked CLAUDE.local.md). Move them to the committed project file. Check where the configuration lives before touching wording.

Settings: scopes, precedence and what merges

Claude Code reads ~/.claude/settings.json (user), .claude/settings.json (shared project, commit it), .claude/settings.local.json (personal to one project, kept out of git) and managed settings delivered by the organisation. The same key resolves from the highest source that sets it: managed > command line > project local > shared project > user. List keys such as permissions.allow are combined across files rather than replaced, so a developer can add entries but cannot remove a managed rule. Permission rules evaluate deny, then ask, then allow; the first match wins and an allow rule cannot carve an exception out of a deny.

Common misplacements: permissions, hooks and env belong in a settings file, not in ~/.claude.json (app state); project MCP servers belong in .mcp.json at the repository root, not under a mcpServers key in settings.json; and some committed content waits until each teammate trusts the folder.

Sharing skills, subagents and MCP servers

Skills live in .claude/skills/<name>/SKILL.md. Old .claude/commands/ files still work. Set disable-model-invocation: true on workflows with side effects so only a person triggers them. On a name collision, enterprise beats personal, which beats project.
Subagents live in .claude/agents/; check them in.
MCP servers have local (default), project and user scope. Project scope writes .mcp.json, which is shared through git; interactive sessions ask for approval before using a project server, but claude -p cannot show that prompt and loads them without asking. Use ${VAR} expansion for secrets so tokens are never committed. The whole server entry from the highest-priority scope wins; fields are not merged.
Plugins bundle skills, hooks, subagents and MCP servers for distribution across repositories.

Managed policy and rollout

Managed settings sit above every other level and reach the fleet by one of four routes, highest priority first: server-managed settings from the claude.ai admin console (Teams and Enterprise plans), an OS policy (macOS plist or Windows HKLM registry), a file-based managed-settings.json (with an optional managed-settings.d/ directory) in a system directory, and the user-writable HKCU registry, which is a convenience default rather than an enforcement channel. By default the highest source that carries a policy key supplies the policy for most keys. Deployments on Bedrock, Google Cloud or Foundry do not fetch server-managed settings directly, so they use file or OS delivery (or a Claude apps gateway).

What to enforce is an architectural choice. The admin-setup page lists the levers: permission lockdown (allowManagedPermissionRulesOnly, permissions.disableBypassPermissionsMode), sandboxing, a managed CLAUDE.md, MCP allow/deny lists (allowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly), plugin marketplace limits, allowManagedHooksOnly, availableModels, login enforcement and a version floor. Enforce the small set that is irreversible or compliance-bound; leave conventions to repository-level guidance that each team owns and reviews like code.

Limits of enforcement worth knowing

A managed model is a default, not a lock: availableModels restricts the choice. A machine administrator can edit a managed file, which is why MDM redeploys it and why HKLM and macOS managed preferences exist. Managed settings bind Claude Code only. Bash rules match the command text, so Bash(rm *) does not stop /bin/rm, and denying WebFetch does not stop curl through Bash; pair rules with the OS-level sandbox or a hook when the restriction must hold. Verify a rollout by running /status and reading the Setting sources line.

Exam traps

A new developer's Claude Code ignores team conventions, so the team adds stronger wording or an MCP server to fix it.

The usual cause is placement: the conventions sit in one developer's ~/.claude/CLAUDE.md, which never travels through git. Commit them to the project CLAUDE.md or .claude/rules/, then confirm with /context on the new machine.
Putting a compliance rule (never read .env, never run destructive commands) in CLAUDE.md, or assuming the most specific CLAUDE.md wins a conflict.

CLAUDE.md is context, files are concatenated rather than overridden, and Claude may resolve contradictions arbitrarily. Rules that must hold belong in permission rules, the sandbox or a hook, ideally in managed settings.
Treating a Bash deny rule or a WebFetch deny as a hard network or filesystem boundary.

Bash rules match the literal command text and do not cover the same program invoked another way, and blocking WebFetch leaves curl or wget available through Bash. Use sandboxing (OS-level filesystem and network isolation) or a PreToolUse hook for a guarantee.
Setting a managed model and assuming developers can no longer choose another one, or committing project settings and assuming they override organisation policy.

A managed model is only a starting default; availableModels is the restriction. And managed settings rank above project, local and command-line settings, so a repository file cannot loosen them.

Practice question

A financial firm with several hundred developers on MDM-managed Mac and Linux machines wants three things: no developer can switch Claude Code into bypassPermissions mode, every session sees the firm's security standards, and each repository keeps its own team conventions. Which architecture fits best?

A Put all three sets of rules in a CLAUDE.md at every repository root, reviewed by each team, and ask every team to keep the organisation-wide sections current.
CLAUDE.md is advisory context and cannot stop anyone from enabling bypass mode. It also gives no single place to change the organisation-wide standards and depends on every repo carrying the file.
B Commit .claude/settings.json to every repository with the bypass-mode lockdown and rely on code review and a CI check to keep it in place in every repository.
Project settings are per repository, rank below managed settings (and below a developer's own local file), and coverage depends on every repo carrying the file. That is not an organisation-level guarantee.
C Use managed settings (MDM or a file) to disable bypass mode, a managed CLAUDE.md for the security standards, and repository CLAUDE.md and .claude/rules/ for team conventions. Correct
Each requirement lands in the mechanism with the right scope and guarantee: an enforced managed setting for the mode lockdown, a managed CLAUDE.md that cannot be excluded for organisation-wide instructions, and version-controlled repository files for team conventions that the teams own.
D Deploy only a managed CLAUDE.md that contains the security standards and every team's conventions, and remove repository-level configuration entirely.
A managed CLAUDE.md is guidance, so it cannot enforce the bypass-mode lockdown. It also pulls team-owned conventions into a central file that the teams cannot version with their code.

Build exercise: Design, stage and prove a team Claude Code configuration

Intermediate · 75 minutes

You'll practice:

Classify team requirements by scope and guarantee (advisory, enforced, on-demand)
Build a shared project layer: CLAUDE.md, path-scoped rules, settings, a skill and an MCP server
Draft and test a managed-settings policy without touching a production machine
Prove scope boundaries by simulating a new teammate and an attempted override

Invent or pick a real team (about 30 developers, one monorepo). Write ten requirements, including at least three 'must never' rules (for example: never read .env files, never git push directly, never bypass permissions) and three per-package conventions. For each, record the mechanism, the scope and the guarantee in a table.

Most scenario questions test whether you match the guarantee to the requirement. Writing the table first forces the decision before any file is created.

You should see: A ten-row table in which every 'must never' row uses an enforced mechanism (permission rule, sandbox, hook or managed setting), every convention row uses CLAUDE.md or a path-scoped rule, and no row relies on ~/.claude/CLAUDE.md for a team rule.
Hints
1. ```
For each row, ask: what happens if Claude ignores this line? If the answer is 'something unacceptable', advice is not enough.
```
2. ```
Use CLAUDE.md or rules for conventions, permissions/sandbox/hooks for prohibitions, skills for rare multi-step workflows, and managed policy for anything the organisation must guarantee.
```
3. ```
Example rows: 'never read .env' -> permissions.deny Read(./.env), managed if org-wide, enforced; 'API handlers validate input with Zod' -> .claude/rules/api.md with paths, advisory; 'release notes workflow' -> skill with disable-model-invocation, on-demand.
```
Build the project layer: a .claude/CLAUDE.md under 200 lines, a path-scoped rule in .claude/rules/, a committed .claude/settings.json with one allow and two deny rules, and a skill at .claude/skills/release-notes/SKILL.md that only a person can trigger. Start Claude Code and check what loaded.

This is the version-controlled layer every teammate receives on clone, so it must contain the shared rules and none of the personal ones.

You should see: /context lists the project CLAUDE.md under Memory files, /permissions shows your allow and deny rules, and /skills lists release-notes.
Hints
1. ```
Which file holds permission rules, and which holds instructions? They are different files with different guarantees.
```
2. ```
Rules use YAML frontmatter with a paths list; the skill needs a folder containing SKILL.md, not a loose .md file; disable-model-invocation goes in the skill's frontmatter.
```
3. ```
settings.json: {"permissions":{"allow":["Bash(npm run *)"],"deny":["Read(./.env)","Bash(git push *)"]}}. Rule file starts with three dashes, then paths: followed by - "src/api/**/*.ts", then three dashes.
```
Add a project-scoped MCP server with claude mcp add --scope project, then edit .mcp.json so any credential comes from an environment variable using ${VAR} syntax. Open /mcp and note the approval state. Write down what changes when the same repository is used by claude -p in CI.

Project MCP servers are shared through git, which makes secret handling and the approval behaviour part of the team design.

You should see: .mcp.json at the repository root containing the server under mcpServers with no literal token; /mcp shows the server and whether it is approved; your note says that non-interactive runs load project servers without an approval prompt.
Hints
1. ```
Where does project scope store the configuration, and is that file committed or private?
```
2. ```
Use claude mcp add --transport http --scope project <name> <url>, then put an Authorization header value of Bearer ${MY_TOKEN} in .mcp.json so the secret lives in each developer's or runner's environment.
```
3. ```
In CI you cannot answer an approval prompt: -p loads project-scoped servers without asking, so treat .mcp.json changes in pull requests as security-relevant and review them like workflow files.
```
In a disposable VM or container (not your workstation), draft a managed policy at /etc/claude-code/managed-settings.json that denies reading .env files, disables bypass mode and makes managed rules the only source of permission rules. Start Claude Code, then try to override it from .claude/settings.local.json.

You need first-hand evidence of the precedence rule: lower scopes can add entries but cannot loosen managed policy.

You should see: /status shows managed settings on the Setting sources line; /permissions shows the deny rule; your attempt to allow reading .env from the local file has no effect.
Hints
1. ```
Which file path does Claude Code read for file-based managed settings on Linux?
```
2. ```
Use a JSON file with a permissions object plus the allowManagedPermissionRulesOnly key (confirm its placement in the settings reference), then restart the session and read /status.
```
3. ```
{"permissions":{"deny":["Read(./.env)"],"disableBypassPermissionsMode":"disable"},"allowManagedPermissionRulesOnly":true}. Save it as /etc/claude-code/managed-settings.json in the container and test from a project directory.
```
Simulate a new teammate: clone the repository into a fresh directory and start Claude Code with CLAUDE_CONFIG_DIR pointing at an empty directory. Compare /context with your own session.

This reproduces the exam's favourite failure (personal configuration mistaken for team configuration) and proves that only committed files travel.

You should see: The clean session lists the project CLAUDE.md and rules but none of your ~/.claude content; anything you had only in user-level config is missing.
Hints
1. ```
What does the new developer have that you do not, and what do you have that they do not?
```
2. ```
CLAUDE_CONFIG_DIR redirects where Claude Code keeps user-level settings, so an empty directory approximates a machine that has never been configured.
```
3. ```
Run: CLAUDE_CONFIG_DIR=/tmp/claude-clean claude from the fresh clone, then /context. Move anything missing that the team needs from ~/.claude into the repository, commit it and re-test.
```
Write a one-page rollout plan: pilot group, who owns each configuration layer, how changes are reviewed, what is enforced versus advised, how you verify the fleet, and how you would observe adoption and spend.

The architect-level answer is a process, not a folder of files: ownership, review and verification determine whether the configuration stays correct.

You should see: A plan that names an owner for managed policy and for each repository layer, uses /status for verification, states a rollback path, and points to the analytics dashboard or OpenTelemetry export for visibility.
Hints
1. ```
Who is allowed to change managed settings, and how would a bad change be reverted across the fleet?
```
2. ```
Pilot with one team, collect where the guidance failed, promote lessons into rules or hooks, then widen. Keep the managed layer small and stable.
```
3. ```
Sample outline: 1) provider and delivery route, 2) minimal enforced set, 3) repo template with CLAUDE.md, rules, settings and skills, 4) pilot and feedback loop, 5) verification with /status, 6) usage visibility, 7) review cadence for config files.
```

Sources

How Claude remembers your project (CLAUDE.md, rules, AGENTS.md, auto memory) - Anthropic
Claude Code settings files and precedence - Anthropic
Set up Claude Code for your organization (decision map for administrators) - Anthropic
Deploy managed settings - Anthropic
Configure permissions - Anthropic
Connect Claude Code to tools via MCP - Anthropic
Extend Claude with skills - Anthropic
Create custom subagents - Anthropic