Configuration Management

Key points

1. 1

   CLAUDE.md scopes: ~/.claude/CLAUDE.md holds your personal preferences for all projects. ./CLAUDE.md or ./.claude/CLAUDE.md holds team instructions and is committed. CLAUDE.local.md holds personal notes for one project; add it to .gitignore.

2. 2

   Put facts Claude needs in every session in CLAUDE.md: build and test commands, conventions, layout. Aim for under 200 lines per file. Multi-step procedures belong in skills, and area-specific rules belong in .claude/rules/ files with paths frontmatter, which load only for matching files.

3. 3

   CLAUDE.md files are combined, not overridden. Ancestor files load at launch and subdirectory files load when Claude reads files there. If two instructions contradict each other, Claude may follow either, so remove the conflict. @path imports pull in other files.

4. 4

   CLAUDE.md is context, not enforcement. Anything that must be blocked, such as reading .env files, needs permission deny rules or a PreToolUse hook.

5. 5

   settings.json scopes: user (~/.claude/settings.json), shared project (.claude/settings.json, committed), project local (.claude/settings.local.json, kept out of git), and managed (policy deployed by the organization).

6. 6

   Precedence, highest first: managed, then command line (--settings, flags), then project local, then shared project, then user. Nothing overrides managed settings, which makes them the place for organization-wide policy.

7. 7

   List keys such as permissions.allow and permissions.deny merge across files instead of replacing each other. A managed availableModels list is the exception: it is applied as-is, and additions in lower-scope files are ignored.

8. 8

   Permission rules are evaluated deny, then ask, then allow, and the first match decides. Specificity does not change that order, so a deny in any file beats an allow elsewhere.

9. 9

   A managed model only sets the model a session starts with, and users can still switch with /model. Model selection is locked with availableModels in managed settings. ANTHROPIC_MODEL in the shell overrides the model key from any file.

10. 10

    Model pinning: every Claude model ID is a fixed snapshot, including the dateless IDs used from the 4.6 generation on. API aliases for earlier models point to the latest dated snapshot, so they can change behavior. Pin IDs in central config and upgrade through reviewed, eval-gated changes.

11. 11

    Treat prompts as code: keep them in version control, change them through reviewed PRs, run the eval gate in CI before promoting, and log the prompt version with each request. Never edit production prompts ad hoc.

12. 12

    Version the model ID, prompt, sampling parameters and tool schemas together as one release configuration, and run evals when any of them changes. A model-only upgrade can break a prompt tuned for the old model.

13. 13

    Plugin dependencies go in the dependencies array of .claude-plugin/plugin.json. Without a version, a dependency tracks the latest release, so pin a tested semver range (e.g. ~2.1.0). A plugin that contains only a name and dependencies works as a team bundle installed with one command.

14. 14

    Enable team plugins and marketplaces for everyone in a repository through the committed project .claude/settings.json (enabledPlugins, extraKnownMarketplaces), not through each developer's local files.

Read the source

• Claude Code settings
• Memory (CLAUDE.md)
• Configure permissions
• Plugin dependencies
• Model IDs and versioning