2.6 — Configuration Management

What You Need to Know

Configuration is anything that changes an application's behaviour without being code. It is managed exactly like code: it lives in version control, changes through review, and reaches environments through the deployment pipeline. For a Claude application, it covers four kinds of artefact.

the CLAUDE.md files and settings.json that a harness surface reads
the prompt files and templates the application assembles requests from
the model identifier each environment targets
the manifest of plugins, connectors and MCP capabilities, with their versions

Take a fabric shop whose Claude assistant answers customer questions about cloth. The assistant runs in dev, staging and production. When it misbehaves, start with an audit. List every behaviour-bearing artefact, then ask which are versioned and recorded. The unversioned one is usually the culprit.

Tracked Versus Local

The Claude Code documentation draws this boundary precisely, and it generalises. .claude/settings.json is the project's shared configuration. It is tracked: checked in and reviewed like any team artefact. .claude/settings.local.json is local: personal and automatically gitignored. User-level settings live outside the repository entirely. Managed settings are the organisation's enforcement layer.

Instruction files split the same way. A project CLAUDE.md, at ./CLAUDE.md or ./.claude/CLAUDE.md, is shared with the team through source control. CLAUDE.local.md stays personal and gitignored.

The management rule follows from that split. Team-shared behaviour goes only in tracked files, and personal preference only in local ones. A behaviour difference between two machines that traces to a local file is working as designed. One that traces to a drifted tracked file is a process failure. At the fabric shop, the team's rule that width fields are stored in centimetres belongs in the project CLAUDE.md. A developer's personal setting for this project goes in .claude/settings.local.json, and their personal instructions in CLAUDE.local.md.

What an Identifier Resolves To

Dated IDs are fixed releases. From the Claude 4.6 generation onward, dateless IDs are also pinned snapshots, not evergreen pointers. For earlier generations, the alias forms are convenience pointers. Each resolves to a dated ID, and that target genuinely moves.

A dateless string can therefore be a pinned snapshot or a moving alias, depending on its generation. So never pattern-match the string. Know exactly what each identifier resolves to, and record which identifier every environment runs. The fabric shop records the identifier for each of its three environments, and what each one resolves to.

Partner platforms add identifiers. On Bedrock, the same snapshot carries an anthropic.-prefixed ID. On Google Cloud, a dated pre-4.6 snapshot carries an @date suffix, while current-generation IDs match the first-party format. Claude Platform on AWS uses first-party IDs throughout. A multi-platform deployment therefore maps one logical model to several platform identifiers. A per-environment record makes that legible.

json

{
  "environment": "production",
  "model": "claude-sonnet-5-5",
  "prompt_version": "turnaround-summary v14",
  "plugins": { "deicing-glossary": "2.3.1" },
  "settings": ".claude/settings.json @ git 41c9f2d"
}

Migrations are deliberate and run in this order.

Run the eval suite against the candidate snapshot.
Change the pinned identifier in configuration, through review.
Deploy through the pipeline.
Audit usage for keys still calling the old model.

Retirement comes with at least 60 days' notice. A retired model fails every request, so the sequence matters more than the speed. Given notice, the fabric shop runs its evals before touching the pin.

Prompt Versioning and Environment Parity

A prompt is a release artefact. It carries a version and a changelog entry saying what changed and why. Its rollback path is a revert.

Parity is the companion control. Each environment runs a known, recorded configuration: prompt versions, model identifier, settings and plugin versions. The environments are then provably comparable, so "staging passed" is evidence about production.

Two parity failures are classic. One is a production hot-fix never backported, which leaves staging testing a prompt production no longer runs. The other is environments silently targeting different model identifiers. Both stay invisible until an incident, because nothing records the difference. Fixing the immediate drift is half the job. The other half is the record-keeping that makes the next divergence visible. The fabric shop keeps that record for all three environments, prompt version included.

Plugin Pinning and Secrets Hygiene

Plugins, connectors and MCP-backed capabilities are dependencies with behaviour, so they get dependency treatment. Each gets an explicit manifest entry, a pinned version and a per-environment record. Upgrades arrive as reviewed changes, run against the eval suite. An unpinned plugin floating on latest is an unreviewed behaviour change on someone else's schedule. The fabric shop pins its care-label plugin for that reason.

Secrets never join the versioned artefacts. API keys never live in settings files. The documented patterns are credential helpers (apiKeyHelper generates tokens on demand) and runtime environment variables. The fabric shop's key comes from a helper or an environment variable. A committed key lives in history long after it's deleted from the file. Encrypting it still leaves a key in history. Gitignoring the settings file takes away a shared file that other configuration still needs.

In the exam

Questions on this sub-skill hand you a misbehaving system and reward the audit described above. For model identifiers, the exam answer is still "pin a specific version and migrate deliberately". As of August 2026 the real risks are the pre-4.6 alias and the missing record, not a dateless model string as such. Encrypting a committed key and gitignoring the settings file are the distractor mitigations. Adversarial handling of a leaked secret is Domain 7. Not committing secrets is covered here.

The Domain 3 boundary

Precedence order and hierarchy semantics, how Claude Code consumes settings and CLAUDE.md, are Domain 3 keys. A 2.6 item asks about management: what to track, pin, review and keep in parity. An answer that explains precedence when the question is discipline is the lure, not the key.

Exam Traps

Exam Trap

Swapping the tracked and local files: treating settings.local.json as team-shared or project CLAUDE.md as personal.

The documented boundary is exact. Project settings.json and project CLAUDE.md are shared and checked in; settings.local.json and CLAUDE.local.md are personal and gitignored. Distractors swap exactly one of the four.

Exam Trap

Flipping production to a new model first and evaluating afterwards, because the deprecation clock is ticking.

The keyed migration sequence is eval the candidate snapshot first, then change the pinned identifier through the release process, then audit for stragglers. Sixty days of notice exists precisely so the sequence never needs inverting.

Exam Trap

Assuming any dateless model string is a moving alias that must be replaced with a dated one.

Current-generation dateless IDs are pinned snapshots, while pre-4.6 aliases genuinely move. The discipline is knowing and recording what each identifier resolves to per environment, not pattern-matching the string.

Exam Trap

Fixing a committed API key by encrypting it in place or gitignoring the settings file.

The settings file is a shared artefact other configuration still needs, and an encrypted key in history is still a key in history. The keyed hygiene moves credentials out of versioned files entirely, via a credential helper or runtime environment variables.

Practice Scenario

A ground-handling company runs a Claude-based aircraft-turnaround report tool in dev, staging and production. Production output quality dropped this week while staging stayed clean. An audit finds: the production system prompt was hot-fixed six weeks ago and never backported; production and staging run different versions of the de-icing glossary plugin; the model identifiers match everywhere. What is the correct course of action?

Option AAssemble the prompt at runtime from the application environment variables instead of files, so no prompt artefact remains on disk to drift between environments, and close the incident

Option BBackport the hot-fix through review, align and pin the plugin version in both environments, and record every behaviour-bearing artefact per environment so drift is visible

Option CFreeze all configuration changes to production until the next quarterly release, so no further divergence can accumulate

Option DCopy the staging prompt over the hot-fixed production version, since staging is the environment that currently passes evaluation and should be treated as the source of truth

Build Exercise

Audit One Repository's Configuration Surface

Difficulty

35 minutes

What you'll learn

How to enumerate every behaviour-bearing artefact in a real repository
How to place files correctly across the tracked-versus-local boundary
How to build the per-environment configuration record
How to rehearse a model migration in the right sequence

In a real Claude application repository, list every behaviour-bearing artefact: CLAUDE.md files, settings files, prompt files and templates, the model identifier, and every plugin or MCP capability with its version
Why: The audit instinct the exam rewards starts with an exhaustive inventory; anything missed here stays unmanaged.
You should see: A list of eight or more artefacts, each one capable of changing behaviour without a code change.
Check each artefact against the tracked-versus-local boundary and fix any file on the wrong side, confirming no secrets sit anywhere versioned
Why: The documented boundary is a keyed fact, and applying it to real files beats memorising the four names.
You should see: Shared behaviour in checked-in files, personal preference in gitignored ones, credentials in a helper or environment variables only.
Record what each model identifier resolves to (dated snapshot, current-generation pinned dateless ID, or a pre-4.6 alias) and write the per-environment configuration record for dev, staging and production
Why: The record is the control that makes drift visible, and classifying identifiers correctly is where the docs have moved on.
You should see: A record per environment naming prompt version, model identifier, settings revision and plugin versions.
Add a version header and changelog to the main prompt file, then make one prompt change through a branch, review and merge
Why: Prompt versioning becomes real the first time a prompt change rides the pipeline with history and a rollback path.
You should see: A merged change whose diff, reviewer and revert path all exist.
Simulate a model migration on paper: the candidate identifier, the eval suite to run first, the configuration change that flips the pin, and the usage audit confirming no key still targets the old model
Why: Rehearsing the sequence before a deprecation notice arrives is what turns a 60-day clock into a routine release.
You should see: Four ordered steps with the eval run explicitly before the pin change.

Sources

Claude Code settings — Claude Docs, the settings.json scopes, the auto-gitignored local file and apiKeyHelper
How Claude remembers your project — Claude Docs, project CLAUDE.md versus gitignored CLAUDE.local.md
Models overview — Claude Docs, what dated, dateless and alias identifiers resolve to
Model deprecations — Claude Docs, the migration clock the pinning discipline plans against
Claude Certified Developer Foundations Exam Guide — Domain 2, Configuration Management — Anthropic