2.8 Configuration Management: Versioning Every Layer
2.8.1 CLAUDE.md as Versioned Project Memory
CLAUDE.md is project/repo memory and instructions for Claude Code -- the persistent context that shapes how Claude Code behaves inside a given repository. Because it directly shapes agent behavior, it should be checked into version control just like source code: changes to it are reviewable, diffable, and revertible through the same PR process as any other change, not a personal scratch file that lives outside that process.
Where this shows up on the exam
Treating CLAUDE.md as a personal, untracked local file rather than checked-in project memory is the recurring trap here -- it belongs in version control and code review exactly like the code it sits alongside.
2.8.2 settings.json as the Enforced Configuration Surface
settings.json is Claude Code's settings surface: permissions, hooks, tool allow/deny lists, and environment configuration. This is where deterministic, structural controls get configured -- which tools are permitted, what hooks fire at which points, and what environment the agent runs in -- as distinct from prompt-level guardrails, which are advisory rather than enforced.
{
"permissions": {
"allow": ["Bash(npm run test:*)", "Read", "Grep"],
"deny": ["Bash(rm -rf *)", "Bash(git push --force*)"]
},
"hooks": {
"PreToolUse": [{ "matcher": "Bash", "command": "./scripts/audit-log.sh" }]
},
"mcpServers": {
"internal-crm": { "command": "npx", "args": ["@acme/crm-mcp-server"] }
},
"model": "claude-sonnet-4-5"
}settings.json is not a one-time setup step. It's an ongoing configuration surface that evolves with the project -- permissions get tightened or loosened, hooks get added, and it needs exactly the same version-control discipline as CLAUDE.md, for the same reason: it materially changes agent behavior.
2.8.3 Model-Version Pinning: Reproducibility Over Convenience
Pin an explicit model ID -- something like claude-sonnet-4-5 -- in production rather than a floating alias like "latest." A floating alias is a reproducibility hazard: a silent model update on Anthropic's side can change behavior underneath an application that never touched its own code. The discipline is to pin the version and upgrade deliberately, only after re-running evaluations against the pinned prompt/model pair, exactly as covered in 2.2's SDLC treatment of model-version pinning.
| Approach | Consequence |
|---|---|
| Floating alias in production | Behavior can silently change on Anthropic's release schedule, with no code change on your side |
| Pinned explicit model ID | Behavior stays reproducible; you control exactly when and whether to upgrade |
The same tradeoff as 2.2's SDLC treatment, applied here as a configuration-management discipline.
2.8.4 Prompt Versioning & Plugin Dependencies
Treat prompts as artifacts with version history, the same as source code: diffable, reviewable, and revertible. This is what makes it possible to correlate a quality change in production to a specific prompt change, rather than guessing which of several untracked edits caused a regression. Without that history, a regression is nearly unfalsifiable -- you have no way to point at the exact change that caused it.
Track which plugins and MCP servers a project depends on, and at what versions, exactly like any other software dependency -- a package in a lockfile is the right mental model. An untracked plugin update is just as capable of silently changing behavior as an untracked model update, and deserves the same tracking discipline.
- 1.CLAUDE.md -- version-controlled, reviewed like code.
- 2.settings.json -- version-controlled, reviewed like code.
- 3.Model ID -- pinned explicitly, upgraded only after re-run evals.
- 4.Prompts -- versioned with diffable history, correlatable to quality changes.
- 5.Plugin/MCP-server dependencies -- tracked with explicit versions, like any lockfile dependency.
Exam trap
Relying on a floating "latest" model alias in production is the signature trap in this task statement. A silent model update can change behavior; the correct pattern is pinning the version and gating upgrades behind re-run evals -- exactly the same discipline applied to CLAUDE.md, settings.json, prompts, and plugin dependencies.
2.8.5 One Discipline, Five Artifacts
Configuration management in this domain isn't five unrelated rules -- it's one discipline (version, review, pin deliberately) applied to five different artifacts that all shape a Claude application's behavior: CLAUDE.md, settings.json, the model ID, prompts, and plugin/MCP-server dependencies. The common failure mode across all five is treating one of them as exempt from that discipline because it "isn't really code" -- a memory file, a settings blob, a string identifier, a piece of natural-language text, or a third-party connection.
| Artifact | Discipline applied |
|---|---|
| CLAUDE.md | Version-controlled, reviewed like code |
| settings.json | Version-controlled, reviewed like code |
| Model ID | Pinned explicitly, upgraded only after re-run evals |
| Prompts | Versioned with diffable history |
| Plugin/MCP-server dependencies | Tracked with explicit versions, like a lockfile |
Five different artifacts, one shared discipline: nothing that shapes behavior is exempt from version control, review, and deliberate change management.
On the exam, if a question describes any of these five artifacts being changed casually, silently, or without review -- regardless of which one it is -- the gap it's testing is the same: configuration that materially affects behavior needs the same versioning and review discipline as code, full stop.
Key Takeaways
- ✓CLAUDE.md is project/repo memory for Claude Code and belongs in version control, reviewed like code -- not a personal untracked scratch file.
- ✓settings.json configures permissions, hooks, tool allow/deny lists, and environment; it's an ongoing configuration surface, not a one-time setup step.
- ✓Pin an explicit model ID in production; a floating "latest" alias is a reproducibility hazard. Gate every upgrade behind re-run evaluations.
- ✓Version prompts like code so a quality regression can be traced to a specific prompt change and rolled back.
- ✓Track plugin/MCP-server dependencies and their versions like any other software dependency -- an untracked update is a silent-behavior-change risk just like an untracked model update.
Check Your Understanding
Test what you learned in this lesson.
Q1.A production Claude Code deployment pins its model to a floating "latest" alias so it always uses the newest release automatically. What risk does this introduce?
Q2.A developer keeps their project's CLAUDE.md as a local file, never committed, and edits it freely without review. What's the issue per configuration-management practice?
Q3.Why version prompts the same way source code is versioned?
Q4.A project has three MCP servers connected, but nobody has documented their versions or what happens when an upstream maintainer pushes an update. What configuration-management gap does this describe?
Practice This Lesson