2.6 Configuration management
What counts as configuration
| Artifact | Governs | Lives in |
|---|---|---|
CLAUDE.md | Standing instructions for Claude Code in a repo | Repo (committed) or ~/.claude/ (personal) |
.claude/rules/ | Path-scoped instructions | Repo |
settings.json | Permissions, hooks, environment variables, model, MCP enablement | Repo .claude/settings.json, local .claude/settings.local.json, user ~/.claude/settings.json |
.mcp.json | Project MCP servers | Repo |
| Skills, commands, subagents | On-demand behaviour | .claude/skills/, .claude/commands/, .claude/agents/ |
Model ID, effort, max_tokens, beta headers | API runtime behaviour | Application config / environment |
| Prompt and schema versions | Model-facing contract | Repo, versioned |
| Plugin list and versions | Bundled configuration | Repo / plugin config |
The CLAUDE.md hierarchy
| Level | Path | Shared via version control? | Scope |
|---|---|---|---|
| User | ~/.claude/CLAUDE.md | No | That user, across all their projects |
| Project | CLAUDE.md at the repo root, or .claude/CLAUDE.md | Yes | Everyone who clones the repo |
| Directory | CLAUDE.md in a subdirectory | Yes | Work touching that subtree |
"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
{
"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" }] }
]
}
}
| File | Scope | Committed? |
|---|---|---|
.claude/settings.json | Project, team-wide | Yes |
.claude/settings.local.json | Project, this machine only | No — gitignored |
~/.claude/settings.json | All of that user's projects | No |
| Enterprise managed settings | Organisation-wide, administrator-controlled | Deployed 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
| Practice | Detail |
|---|---|
| Pin the exact model ID string | claude-opus-5. Never append a date suffix you recall from elsewhere; never rely on a floating alias |
| Keep it in config, not literals | One place to change, one place to roll back, no code edit for a canary |
| Store the model ID with the output | Regressions must be attributable to a version |
| Treat a bump as a change | Eval run, canary, rollback plan (2.2) |
| Re-baseline tokens after a tokenizer change | Cost models built on the old tokenizer are wrong |
| Pin beta headers too | A beta flag is part of the request contract |
| Discover capabilities at runtime, not from memory | client.models.retrieve(id) reports max_input_tokens, max_tokens, capabilities |
Prompt versioning
Prompts are the model-facing contract. Version them like an API.
| Practice | Detail |
|---|---|
| In the repo, as files | Diffable and reviewable; a prompt change is a PR |
| A version identifier in the artifact | Logged with each response so behaviour is attributable |
| Eval results tied to the version | "Which prompt scored 94%?" must be answerable |
| One change per commit | Otherwise a bisect cannot isolate the regression |
| Stable prefix, volatile suffix | Prompt structure is also a cache decision — reordering for tidiness can silently kill the cache |
| Retire dead scaffolding | Instructions written for an older model often hurt a newer one |
Plugin dependencies
| Question to answer in the repo | Why |
|---|---|
| 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 |
"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
- 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?
- Question 2
Two developers on the same repository at the same commit get different Claude Code behaviour. What do you check first?
- 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?