# Claude Code Configuration Capabilities

> Source: Official Claude Code documentation (code.claude.com/docs), 75 pages, verified 2026-04-03.
> Delta layer: research/03-claude-code-changes-config-surfaces.md (verified 2026-04-19) — sandbox/managed-only/prompt-cache surfaces added between v2.1.14 and v2.1.114.

## 2026-04 deltas (research/03)

| Surface | Added in | Notes |
|---------|---------|-------|
| `sandbox.*` (filesystem.allowRead/denyRead, network.deniedDomains/allowedDomains, enabled, failIfUnavailable, allowUnsandboxedCommands, enableWeakerNetworkIsolation) | ~v2.1.77–v2.1.83 | Sandbox configuration surface; managed-only variants exist for enterprise lockdown. |
| `allowManagedHooksOnly`, `allowManagedMcpServersOnly`, `allowManagedPermissionRulesOnly`, `sandbox.filesystem.allowManagedReadPathsOnly`, `sandbox.network.allowManagedDomainsOnly` | ~v2.1.83–v2.1.84 | Enterprise policy enforcement — block any non-managed hook/MCP/permission. |
| `disableSkillShellExecution` | v2.1.91 | Disables `!command` shell expansion in skill bodies. Prompt-injection mitigation. |
| `forceRemoteSettingsRefresh` | v2.1.92 | Fail-closed on managed-settings fetch failure. |
| `showClearContextOnPlanAccept` | v2.1.77 | Plan-mode opt-in to clear context after plan accept. |
| `showThinkingSummaries` | v2.1.113 (default flipped to false) | Now opt-in. |
| `tui`, `autoScrollEnabled` | v2.1.111 | Fullscreen terminal UI mode. |
| `attribution.commit`, `attribution.pr` | 2026-04 | Granular replacement for legacy `includeCoAuthoredBy`. |
| Env: `ENABLE_PROMPT_CACHING_1H`, `FORCE_PROMPT_CACHING_5M` | v2.1.108 | Explicit prompt-cache TTL control. |
| Env: `CLAUDE_CODE_DISABLE_1M_CONTEXT`, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 2026-04 | Behavior opt-outs for new defaults. |

## Official Configuration Guidance (Anthropic)

These principles are backed by official docs and verified community reports. Use them to ground recommendations.

### Core Architecture

- **CLAUDE.md is advisory, not enforced.** It's injected as user-message context — Claude reads it and tries to follow it, but there is no guarantee of strict compliance. Compliance depends on specificity and file length.
- **settings.json is the enforcement layer.** Permissions, sandbox rules, and tool grants are enforced by the client regardless of what Claude decides to do.
- **Hooks are deterministic.** Unlike CLAUDE.md instructions which are advisory, hooks guarantee the action happens every time with zero exceptions.

### Proven Impact

- **CLAUDE.md over 200 lines degrades adherence.** GitHub issue #22503 documents 300-line CLAUDE.md being "ignored 80+ times." Official docs now explicitly call this out: "important rules get lost in the noise."
- **Path-scoped rules reduce context noise.** Rules without `paths:` frontmatter load every session regardless of relevance. Scoped rules trigger only when Claude reads matching files.
- **Conflicting instructions cause arbitrary behavior.** When CLAUDE.md contains contradictions, Claude picks one arbitrarily. No priority mechanism resolves conflicts within a single CLAUDE.md.
- **System prompt takes precedence over CLAUDE.md.** Built-in system prompts (plan mode, agent launching) can override user-defined CLAUDE.md instructions.

### When Each Feature Is Relevant

| Feature | Relevant when... | Not needed when... |
|---------|-----------------|-------------------|
| permissions.deny | Sensitive files exist (.env, secrets/) | Fully trusted solo dev environment |
| hooks | Repeatable automation or safety checks needed | Occasional manual workflows |
| path-scoped rules | Multiple languages, contexts, or large codebase | Single-language, small project |
| MCP servers (.mcp.json in git) | Team shares tool access | Solo project, personal tools only |
| custom agents | Specialized parallel workflows | Linear single-task coding |
| custom skills | Repeated multi-step workflows | One-off tasks |
| CLAUDE.local.md | Personal preferences differ from team | Solo developer |
| model overrides | Different tasks need different cost/capability | Default model works for all tasks |
| output styles | Team has specific formatting needs | Default style is sufficient |
| managed settings | Organization-wide policy enforcement | No org, solo developer |

---

## 1. CLAUDE.md — Project Memory

**What it is:** Markdown file injected into every session as user-message context.

| Scope | Location |
|-------|----------|
| Project (shared) | `./CLAUDE.md` or `./.claude/CLAUDE.md` |
| Project (personal) | `./CLAUDE.local.md` (gitignored) |
| User (all projects) | `~/.claude/CLAUDE.md` |
| Org-managed (macOS) | `/Library/Application Support/ClaudeCode/CLAUDE.md` |
| Org-managed (Linux) | `/etc/claude-code/CLAUDE.md` |

**Key features:** `@import` syntax inlines other files (max 5 hops); HTML comments `<!-- -->` stripped before injection (free maintainer notes); lazy loading of subdirectory files; `claudeMdExcludes` setting skips files by glob.

**Fully utilizing:** CLAUDE.md under 200 lines with clear headers; `@import` for large specs; `CLAUDE.local.md` for personal sandbox URLs; auto-memory enabled.

**Common gaps:** No `CLAUDE.local.md`; no `@imports` (one huge file); no user-level `~/.claude/CLAUDE.md`; file over 200 lines reducing adherence.

---

## 2. CLAUDE.local.md — Personal Project Config

**What it is:** Companion to CLAUDE.md; appended after it; gitignored by default.

**Config location:** `./CLAUDE.local.md` (project root)

**Key fields/options:** Free-form markdown, same syntax as CLAUDE.md. Ideal for personal API keys, sandbox URLs, local dev notes.

**Fully utilizing:** Personal overrides that shouldn't be committed; local tool paths; developer-specific preferences.

**Common gaps:** File never created; personal preferences mixed into shared CLAUDE.md.

---

## 3. ~/.claude/CLAUDE.md — User-Level Memory

**What it is:** Loaded for every project; lower precedence than project CLAUDE.md.

**Config location:** `~/.claude/CLAUDE.md`

**Key fields/options:** Same markdown as project CLAUDE.md; `@import` supported.

**Fully utilizing:** Personal coding style, preferred tools, communication preferences applied everywhere.

**Common gaps:** File never created; duplicating same instructions in every project CLAUDE.md.

---

## 4. User Rules — ~/.claude/rules/

**What it is:** Personal rules files that load based on path patterns.

**Config location:** `~/.claude/rules/*.md`

**Key fields/options:** YAML frontmatter `paths:` field with glob patterns — file loads only when Claude works on matching paths. Symlinks supported. Recursive discovery.

```yaml
---
paths: ["src/**/*.ts"]
---
# TypeScript-specific rules here
```

**Fully utilizing:** Separate rule files per language, per domain, per tool; prevents irrelevant rules loading.

**Common gaps:** No `~/.claude/rules/` at all; everything in one CLAUDE.md that always loads.

---

## 5. Project Rules — .claude/rules/

**What it is:** Project-scoped rules with path-specific activation.

**Config location:** `./.claude/rules/*.md`

**Key fields/options:** Same `paths:` frontmatter as user rules. Committed to git for team sharing.

**Fully utilizing:** TypeScript rules only load for `.ts` files; migration rules only load for `db/**` paths; test rules only load for `**/*.test.*`.

**Common gaps:** No `.claude/rules/` directory; path-specific rules not used; all rules always load.

---

## 6. Org-Managed CLAUDE.md

**What it is:** Org-controlled instructions that cannot be overridden by users.

**Config locations:** `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows)

**Fully utilizing:** Org-wide security policies, required compliance notes, standard workflow rules.

**Common gaps:** Not used in org deployments; individual teams manage their own configs without coordination.

---

## 7. Project settings.json

**What it is:** Project-level settings committed to git; shared with team.

**Config location:** `./.claude/settings.json`

**Key fields:** `permissions.allow/deny/ask`, `env`, `hooks`, `model`, `effortLevel`, `attribution`, `enabledPlugins`, `enableAllProjectMcpServers`

**Fully utilizing:** Team-agreed allow/deny rules; project env vars; attribution config; plugin list for team.

**Common gaps:** File doesn't exist; no permissions configured; no env block; missing `$schema` line.

---

## 8. User settings.json

**What it is:** Personal settings applied to all projects.

**Config location:** `~/.claude/settings.json`

**Key fields:** `model`, `effortLevel`, `outputStyle`, `language`, `statusLine`, `autoMemoryEnabled`, `autoMemoryDirectory`, `hooks`, `defaultShell`, `voiceEnabled`, `editorMode` (in `~/.claude.json`)

**Fully utilizing:** Personal model preference; default effort level; status line config; user-level hooks.

**Common gaps:** File never touched; relying on project settings only; no personal preferences set.

---

## 9. Local settings.json

**What it is:** Per-project personal overrides; gitignored.

**Config location:** `./.claude/settings.local.json`

**Key fields:** Same as project settings.json; `autoMode` classifier (user/local settings only, not project).

**Fully utilizing:** Local dev API endpoints; personal permission overrides; local-only env vars.

**Common gaps:** Never created; personal overrides committed to shared settings.json.

---

## 10. Managed Settings

**What it is:** Org-controlled settings at highest precedence; cannot be overridden.

**Config locations:** `managed-settings.json` in system dirs; `managed-settings.d/*.json` (alphabetical merge)

**Key fields (managed-only):** `allowedMcpServers`, `deniedMcpServers`, `allowManagedMcpServersOnly`, `allowManagedHooksOnly`, `allowManagedPermissionRulesOnly`, `allowedChannelPlugins`, `blockedMarketplaces`, `strictKnownMarketplaces`, `pluginTrustMessage`

**Fully utilizing:** Lock MCP servers to org-approved list; enforce hook policies; org announcements via `companyAnnouncements`.

---

## 11. .mcp.json — Project MCP Config

**What it is:** Project-level MCP server configuration; committed to git.

**Config location:** `./.mcp.json`

**Key fields:**
```json
{
  "mcpServers": {
    "name": {
      "type": "stdio|http",
      "command": "...", "args": [...],
      "url": "...",
      "env": {}, "timeout": 30000, "trust": "workspace|trusted|untrusted"
    }
  }
}
```

**Fully utilizing:** Team-shared MCP servers (GitHub, Jira, DBs); MCP resources via `@server:path`; MCP prompts as slash commands; `enableAllProjectMcpServers: true` for zero-friction team onboarding.

**Common gaps:** No `.mcp.json`; MCP only configured in `~/.claude.json` (not shared); trust levels not set; MCP resources not used.

---

## 12. ~/.claude.json — Global Config

**What it is:** Global non-settings preferences (separate file from settings.json).

**Config location:** `~/.claude.json`

**Key fields:** `mcpServers` (user-scope MCP), `autoConnectIde`, `autoInstallIdeExtension`, `editorMode` ("normal"/"vim"), `showTurnDuration`, `terminalProgressBarEnabled`, `teammateMode` ("auto"/"in-process"/"tmux")

**Fully utilizing:** User-level MCP servers; vim mode enabled; IDE auto-connect.

**Common gaps:** MCP servers configured per-project instead of here when they should be global; editorMode never set.

---

## 13. managed-mcp.json — Org MCP Config

**What it is:** Org-managed MCP servers deployed to all users.

**Config locations:** System directories (same as managed-settings.json).

**Key fields:** Same `mcpServers` format as `.mcp.json`.

**Fully utilizing:** Org-wide MCP servers (internal APIs, knowledge bases) available everywhere.

**Common gaps:** Not deployed in org setups; teams configure MCP independently.

---

## 14. keybindings.json

**What it is:** Custom keyboard shortcuts for Claude Code UI.

**Config location:** `~/.claude/keybindings.json` (open with `/keybindings`)

**Key fields:**
```json
{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [{"context": "Chat", "bindings": {"shift+enter": "chat:newline"}}]
}
```

**Key actions:** `chat:submit`, `chat:newline`, `chat:externalEditor`, `chat:cycleMode`, `chat:thinkingToggle`, `chat:fastMode`, `voice:pushToTalk`

**Contexts:** Global, Chat, Autocomplete, Settings, Confirmation, Tabs, Help, Transcript, HistorySearch, Task, ThemePicker, Attachments, Footer, MessageSelector, DiffDialog, ModelPicker, Select, Plugin

**Fully utilizing:** `chat:newline` bound to Shift+Enter; external editor for complex prompts; chord bindings for workflows.

**Common gaps:** File never created; `chat:newline` not bound (most common friction); vim mode not enabled for vim users.

---

## 15. Skills

**What it is:** Custom slash commands with full tool access.

**Config locations:** `~/.claude/skills/<name>/SKILL.md` (user); `.claude/skills/<name>/SKILL.md` (project); `.claude/commands/<name>.md` (legacy)

**Key frontmatter:** `name`, `description`, `argument-hint`, `allowed-tools`, `model`, `effort`, `context` (fork), `agent`, `hooks`, `paths`, `disable-model-invocation`, `user-invocable`, `shell`

**String substitutions:** `$ARGUMENTS`, `$ARGUMENTS[N]`, `$N`, `${CLAUDE_SESSION_ID}`, `${CLAUDE_SKILL_DIR}`

**Dynamic context:** `` !`command` `` executes shell command and inlines output.

**Bundled skills:** `/batch`, `/claude-api`, `/debug`, `/loop`, `/simplify`

**Fully utilizing:** Custom deploy/review workflows; `disable-model-invocation: true` on side-effect skills; `context: fork` for isolated research; `!`git diff HEAD`` for dynamic context; `argument-hint` for UX.

**Common gaps:** No custom skills; skills missing `description` (never auto-invoked); no `!`command`` dynamic context; bundled skills not used.

---

## 16. Agents (Subagents)

**What it is:** Named AI workers with scoped tools, models, and permissions.

**Config locations:** `.claude/agents/<name>.md` (project); `~/.claude/agents/<name>.md` (user); plugin `agents/`; managed `agents/`

**Key frontmatter:** `name`, `description`, `model`, `tools`, `disallowedTools`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory` ("user"/"none"), `effort`, `background`, `isolation` ("worktree"), `color`

**Built-in agents:** `Explore` (read-only, Haiku), `Plan` (read-only), `general-purpose` (all tools), `Claude Code Guide` (Haiku)

**Fully utilizing:** Domain agents (security-reviewer, test-writer); restricted tool sets; Haiku for scanning, Opus for analysis; `isolation: worktree` for parallel work; `memory: "user"` for persistent learning; `maxTurns` guard.

**Common gaps:** No custom agents; no tool restrictions; no model optimization; no persistent memory; no worktree isolation; missing `description` (never auto-delegated).

---

## 17. Plugins

**What it is:** Namespaced bundles of skills + agents + hooks + MCP + tools.

**Config location:** `.claude-plugin/plugin.json` (manifest); enabled via `enabledPlugins` in settings.json

**Key plugin.json fields:** `name`, `description`, `version`, `author`, `homepage`, `repository`, `license`

**Structure:** `skills/`, `agents/`, `hooks/hooks.json`, `.mcp.json`, `.lsp.json`, `bin/`, `settings.json`

**Enabling:**
```json
{"enabledPlugins": {"plugin-name@marketplace": true}}
```

**Fully utilizing:** Team plugins in shared marketplace; org tool bundles (MCP + skills + agents); LSP plugins for all languages; `bin/` for custom CLI tools.

**Common gaps:** No plugins; `.claude/` configs that should be plugins (not shareable); no LSP plugins; no team marketplace configured.

---

## 18. Output Styles

**What it is:** Named system prompt variants that change Claude's default behavior.

**Config locations:** `~/.claude/output-styles/*.md` (user); `.claude/output-styles/*.md` (project); `outputStyle` key in settings.json

**Built-in styles:** `Default` (SE assistant), `Explanatory` (educational Insights blocks), `Learning` (collaborative, TODO(human) markers)

**Custom format:**
```markdown
---
name: My Style
description: What this does
keep-coding-instructions: false
---
Instructions here...
```

**Key distinction:** Output styles replace the system prompt; CLAUDE.md adds a user message. Use output styles when you need stronger enforcement.

**Fully utilizing:** Custom style for documentation/analysis work; `Explanatory` for onboarding; project styles for specialized domains.

**Common gaps:** Never changed from Default; not knowing styles modify the system prompt (vs CLAUDE.md); no custom styles for specialized workflows.