Phase 1: Platform Engineering on Claude Code Wiki

Managed Settings and Security Policy

Mon, 01 Jan 0001 00:00:00 +0000

Managed Settings and Security Policy#

Overview#

The managed-settings.json file is the enterprise-level configuration that sits at the top of Claude Code’s settings hierarchy and cannot be overridden by any developer or project-level setting. It’s deployed to every developer machine via Mobile Device Management (MDM) or configuration management tooling.

Baseline Enterprise Configuration#

{
 "env": {
 "CLAUDE_CODE_USE_BEDROCK": "1",
 "ANTHROPIC_BEDROCK_BASE_URL": "https://llm-gateway.internal.corp.com/bedrock",
 "CLAUDE_CODE_SKIP_BEDROCK_AUTH": "1",
 "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
 },
 "cleanupPeriodDays": 14,
 "permissions": {
 "disableBypassPermissionsMode": "disable",
 "deny": [
 "Read(**/.env)",
 "Read(**/.env.*)",
 "Read(**/secrets/**)",
 "Read(**/.ssh/**)",
 "Read(**/credentials*)",
 "Bash(sudo:*)",
 "Bash(su:*)",
 "Bash(curl:*)",
 "Bash(wget:*)",
 "Bash(ssh:*)",
 "Bash(rm -rf:*)"
 ]
 },
 "allowManagedPermissionRulesOnly": false,
 "allowManagedHooksOnly": false,
 "strictKnownMarketplaces": []
}

Key Design Decisions#

Bedrock Routing (env section)#

CLAUDE_CODE_USE_BEDROCK: Routes all requests through Bedrock instead of api.anthropic.com
ANTHROPIC_BEDROCK_BASE_URL: Points to the internal LLM gateway, not directly to Bedrock
CLAUDE_CODE_SKIP_BEDROCK_AUTH: The gateway holds AWS credentials, developers don’t need them

Telemetry Lockdown#

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC bundles four flags into one:

Developer Environment Standardization

Mon, 01 Jan 0001 00:00:00 +0000

Developer Environment Standardization#

The Problem#

Without standardization, 500 developers debug 500 different environment configurations. Claude Code needs Node.js 18+, correct environment variables, network connectivity to the LLM gateway, and managed settings in the right filesystem location. Every permutation is a support ticket.

Option A: Managed Devcontainers (Recommended for VS Code/Codespaces Orgs)#

If the org uses VS Code or GitHub Codespaces, create a standard devcontainer with everything pre-configured.

// .devcontainer/devcontainer.json
{
 "name": "Enterprise Dev Environment",
 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
 "features": {
 "ghcr.io/devcontainers/features/node:1": { "version": "20" }
 },
 "postCreateCommand": "npm install -g @anthropic-ai/claude-code",
 "containerEnv": {
 "CLAUDE_CODE_USE_BEDROCK": "1",
 "ANTHROPIC_BEDROCK_BASE_URL": "https://llm-gateway.internal.corp.com/bedrock",
 "CLAUDE_CODE_SKIP_BEDROCK_AUTH": "1",
 "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
 },
 "mounts": [
 "source=/Library/Application Support/ClaudeCode,target=/etc/claude-code,type=bind,readonly"
 ]
}

Developer opens repo → devcontainer starts → Claude Code just works.

CLAUDE.md Architecture -- Four-Layer Context Hierarchy

Mon, 01 Jan 0001 00:00:00 +0000

CLAUDE.md Architecture – Four-Layer Context Hierarchy#

The Core Design Problem#

Claude Code has a context window of ~200K tokens. Every CLAUDE.md file, every rule, every skill description, every file Claude reads, every conversation turn competes for space. The context window is the scarce resource, and the platform engineer’s job is to manage it like memory in a constrained system.

Unlike human developers who can skim past irrelevant instructions, Claude treats everything in its context with roughly equal attention. Irrelevant instructions don’t just waste tokens – they actively dilute the signal.

Skills vs. Slash Commands vs. Rules -- Decision Framework

Mon, 01 Jan 0001 00:00:00 +0000

Skills vs. Slash Commands vs. Rules – Decision Framework#

When to Use Rules (.claude/rules/*.md)#

Use rules when the instruction is:

Declarative – “when working on X files, follow Y conventions”
Automatic – should apply without the developer invoking anything
About patterns and constraints, not step-by-step procedures
Path-scopable – different rules for different parts of the codebase

Examples:

API endpoint conventions that apply whenever editing API files
Testing requirements that activate when editing test files
Security constraints that apply globally
Framework-specific patterns (React, Go, etc.)

When to Use Skills (.claude/skills/)#

Use skills when the instruction is:

Skills Library Design -- Three-Tier Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Skills Library Design – Three-Tier Architecture#

Overview#

Skills are structured workflows Claude can invoke as complete procedures. Each skill needs a SKILL.md file with YAML frontmatter (name, description) and markdown instructions. The name becomes the /slash-command, and the description helps Claude decide when to load it automatically.

Tier 1: Organization Skills (Global, All Developers)#

Distributed via plugin marketplace (internal) or symlink from a shared repo. Installed to ~/.claude/skills/ on each developer machine.

Context Budget Worksheet

Mon, 01 Jan 0001 00:00:00 +0000

Context Budget Worksheet#

Purpose#

Before building any CLAUDE.md or skills, do this exercise for each major codebase. It forces discipline about what goes where and prevents context overload.

The Budget#

Claude Code’s context window is approximately 200K tokens. Everything competes for this space: system prompt, CLAUDE.md files, rules, skill descriptions, code files Claude reads, conversation history, and Claude’s own reasoning.

Fixed Costs (Always Loaded)#

These load into every session regardless of what the developer is doing.

Common Failure Modes

Mon, 01 Jan 0001 00:00:00 +0000

Common Failure Modes#

Patterns to watch for and coach against during the rollout.

1. The Encyclopedia CLAUDE.md#

Symptom: A team dumps their entire wiki into CLAUDE.md. 300+ lines of coding standards, architecture descriptions, and process documentation.

Effect: Claude’s responses get slower, less focused, and the context window fills up before any real work happens. Instructions toward the end of a long CLAUDE.md receive less attention than those at the beginning.

What Developers See

Mon, 01 Jan 0001 00:00:00 +0000

What Developers See#

This is the page a team lead hands to developers on day one of rollout.

When a Deny Rule Fires#

Claude Code shows a notification explaining which policy blocked the action and why. The developer always sees what was blocked. For the full incident response workflow (rephrase, manual workaround, or policy exception), see Security Controls.

Checking Effective Permissions#

Run /permissions in any Claude Code session to see all active permission rules and their source (managed, project, user). Run /settings to see the full effective configuration with managed overrides marked.