Skip to main content

2.6 Configuration management

What counts as configuration​

ArtifactGovernsLives in
CLAUDE.mdStanding instructions for Claude Code in a repoRepo (committed) or ~/.claude/ (personal)
.claude/rules/Path-scoped instructionsRepo
settings.jsonPermissions, hooks, environment variables, model, MCP enablementRepo .claude/settings.json, local .claude/settings.local.json, user ~/.claude/settings.json
.mcp.jsonProject MCP serversRepo
Skills, commands, subagentsOn-demand behaviour.claude/skills/, .claude/commands/, .claude/agents/
Model ID, effort, max_tokens, beta headersAPI runtime behaviourApplication config / environment
Prompt and schema versionsModel-facing contractRepo, versioned
Plugin list and versionsBundled configurationRepo / plugin config

The CLAUDE.md hierarchy​

LevelPathShared via version control?Scope
User~/.claude/CLAUDE.mdNoThat user, across all their projects
ProjectCLAUDE.md at the repo root, or .claude/CLAUDE.mdYesEveryone who clones the repo
DirectoryCLAUDE.md in a subdirectoryYesWork touching that subtree
The canonical diagnosis item

"A new teammate isn't getting our conventions." The instructions are in ~/.claude/CLAUDE.md — user level, never shared through version control. Move them to the project level and commit. /memory shows which memory files are actually loaded.

Keep it small. CLAUDE.md is loaded on every session, so it pays tokens forever: universal standards only. Task-specific procedure belongs in a skill, which costs nothing until invoked. Use @path/to/file.md imports to keep the root file short and let each package pull only what it needs.

settings.json​

.claude/settings.json
{
"permissions": {
"allow": ["Bash(npm run test:*)", "Read", "Edit"],
"deny": ["Bash(rm -rf *)", "Read(./.env)"]
},
"env": { "NODE_ENV": "test" },
"hooks": {
"PreToolUse": [
{ "matcher": "Bash", "hooks": [{ "type": "command", "command": ".claude/guard.sh" }] }
]
}
}
FileScopeCommitted?
.claude/settings.jsonProject, team-wideYes
.claude/settings.local.jsonProject, this machine onlyNo — gitignored
~/.claude/settings.jsonAll of that user's projectsNo
Enterprise managed settingsOrganisation-wide, administrator-controlledDeployed by IT

More specific and more privileged scopes win: an enterprise policy overrides a project setting, and a project deny is not something a user setting can loosen. Secrets go in the environment, never in a committed settings file.

Model version pinning​

PracticeDetail
Pin the exact model ID stringclaude-opus-5. Never append a date suffix you recall from elsewhere; never rely on a floating alias
Keep it in config, not literalsOne place to change, one place to roll back, no code edit for a canary
Store the model ID with the outputRegressions must be attributable to a version
Treat a bump as a changeEval run, canary, rollback plan (2.2)
Re-baseline tokens after a tokenizer changeCost models built on the old tokenizer are wrong
Pin beta headers tooA beta flag is part of the request contract
Discover capabilities at runtime, not from memoryclient.models.retrieve(id) reports max_input_tokens, max_tokens, capabilities

Prompt versioning​

Prompts are the model-facing contract. Version them like an API.

PracticeDetail
In the repo, as filesDiffable and reviewable; a prompt change is a PR
A version identifier in the artifactLogged with each response so behaviour is attributable
Eval results tied to the version"Which prompt scored 94%?" must be answerable
One change per commitOtherwise a bisect cannot isolate the regression
Stable prefix, volatile suffixPrompt structure is also a cache decision — reordering for tidiness can silently kill the cache
Retire dead scaffoldingInstructions written for an older model often hurt a newer one

Plugin dependencies​

Question to answer in the repoWhy
Which plugins are installed, at which versions?Reproducible environments; unpinned plugins change behaviour silently
Which MCP servers does each need, and how are they configured?.mcp.json plus environment-variable expansion for credentials
Which binaries or runtimes must be present?A hook or MCP server that shells out fails on a machine without the tool
Which environment variables must be set?Document them; fail loudly on startup if missing
What can each plugin's hooks and tools do?A plugin's hook runs with your privileges — review before enabling
Configuration is the answer more often than it looks

"Behaviour differs between two developers", "it worked yesterday and not today", "the CI run behaves differently from local" — these are configuration-hierarchy and pinning questions, not prompt questions. Check which files are loaded, which settings scope won, and which model ID actually ran.

Quiz​

  1. Question 1

    Quality dropped overnight with no deploy. The configuration names a model family without a version, and nobody can say which model produced yesterday’s outputs. Which change addresses the half of this that made the incident undiagnosable?

  2. Question 2

    Two developers on the same repository at the same commit get different Claude Code behaviour. What do you check first?

  3. Question 3

    A team wants the project CLAUDE.md to stay small while six packages each need detailed standards of their own. Which structure keeps a session’s context cost proportional to the work being done?