345 lines
15 KiB
Markdown
345 lines
15 KiB
Markdown
# Claude Code Configuration Capabilities
|
|
|
|
> Source: Official Claude Code documentation (code.claude.com/docs), 75 pages, verified 2026-04-03.
|
|
|
|
## 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.
|