Settings and the .claude directory

Claude Code’s configuration is layered: user-level settings, project-level settings, local overrides, and — in organisations — server-managed settings that take precedence over all of them.

The .claude directory is where the project-scoped pieces live: settings, skills, subagent definitions, and whatever plugins have installed.

Why the layering causes trouble

The most common Claude Code support question is a variant of “why is it doing that / not doing that”, and the answer is usually that a setting is being overridden a level up or down from where the person is looking.

Anthropic documents a dedicated Debug your configuration page for exactly this. If a hook is not firing or a permission is not applying, start there rather than editing files hopefully.

What lives where

Layer	Typical use
User settings	Your personal preferences, across all projects
Project settings (.claude/)	Team-shared conventions, checked into the repository
Local project settings	Your machine-specific overrides, not committed
Server-managed settings	Organisation policy, set centrally, not user-editable
Environment variables	Runtime overrides, including CI

What it does not do

• It is not the place for secrets. Project settings are committed.
• It is not a substitute for CLAUDE.md. Settings configure the tool; CLAUDE.md instructs the model.
• Automated behaviour cannot be configured by asking. “From now on, always run X after Y” is a hook, not a preference — the harness executes hooks, not the model.