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 is stored in version control, it changes through review, and it 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 (a surface such as Claude Code that assembles instructions for the model) reads
the prompt files and templates the application assembles requests from
the model identifier each environment targets
the manifest (the list) of plugins, connectors and MCP (Model Context Protocol) capabilities, with their versions

This lesson uses one made-up example throughout: a software company that sells an HR product. Its Claude assistant answers employees' questions about paid time off. The assistant runs in dev, staging and production. When it misbehaves, start with an audit. List every artefact that affects its behaviour. Then ask which of those artefacts are versioned and recorded. The unversioned artefact is usually the cause.

Tracked Versus Local

The Claude Code documentation states the boundary between tracked and local files precisely, and the same boundary applies more widely. .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 are stored outside the repository entirely. Managed settings are the settings that the organisation enforces.

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

The management rule comes from that split. Put team-shared behaviour only in tracked files, and put personal preference only in local files. Suppose two machines behave differently. If the difference comes from a local file, the system is working as designed. If the difference comes from a tracked file that differs between the machines, it is a process failure. At the HR software company, the team's rule that time-off balances are stored in hours belongs in the project CLAUDE.md. A developer's personal setting for this project belongs in .claude/settings.local.json. The developer's personal instructions belong in CLAUDE.local.md.

What an Identifier Resolves To

Dated IDs are fixed releases, called snapshots. From the Claude 4.6 generation onward, dateless IDs are also pinned snapshots, not pointers that move. For earlier generations, the alias forms are convenience pointers. Each resolves to a dated ID, and which dated ID it resolves to changes.

A dateless string can therefore be a pinned snapshot or a moving alias, depending on its generation. So never judge an identifier by the form of its string. Know exactly what each identifier resolves to, and record which identifier every environment runs. The HR software team records the identifier for each of its three environments, and what each one resolves to.

Partner platforms add identifiers. On Bedrock, the same snapshot has an anthropic.-prefixed ID. On Claude Models on Google Cloud (Google managed), a dated pre-4.6 snapshot has an @date suffix. Current-generation IDs there 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 record for each environment makes that mapping easy to read.

json

{
  "environment": "production",
  "model": "claude-sonnet-5-5",
  "prompt_version": "time-off-answers v14",
  "plugins": { "holiday-calendar": "2.3.1" },
  "settings": ".claude/settings.json @ git 41c9f2d"
}

Migrations are deliberate and run in this order.

Run the eval suite (the set of tests that scores the application's output) against the candidate snapshot.
Change the pinned identifier in configuration, through review.
Deploy through the pipeline.
Audit usage to find keys that still call 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. When the HR software team gets notice, it runs its evals before it changes the pinned identifier.

Prompt Versioning and Environment Parity

A prompt is a release artefact. It has a version and a changelog entry that says what changed and why. Its rollback is a revert.

Parity is a second control that works together with prompt versioning. 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 well known. One is a production hot-fix (an urgent change made directly in production) that is never backported, so the earlier environments never get it. Staging then tests a prompt that production no longer runs. The other is environments that silently target different model identifiers. Both failures 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 HR software team keeps that record for all three environments, and the record includes the prompt version.

Plugin Pinning and Secrets Hygiene

Plugins, connectors and MCP-backed capabilities are dependencies with behaviour, so treat them as dependencies. Each gets an explicit manifest entry, a pinned version and a per-environment record. Each upgrade is a reviewed change that is run against the eval suite. An unpinned plugin that tracks the latest version is an unreviewed behaviour change, and someone else decides when that change happens. The HR software team pins its holiday-calendar plugin, so the assistant's answers about public holidays change only after a reviewed upgrade.

Secrets are never part of the versioned artefacts. API keys are never stored in settings files. The documented patterns are credential helpers (apiKeyHelper generates tokens on demand) and runtime environment variables. The HR software team's key comes from a helper or an environment variable. A committed key stays in history long after it is deleted from the file. Encrypting the key still leaves a key in history. Gitignoring the settings file removes a shared file that other configuration still needs.

In the exam

Questions on this sub-skill give you a misbehaving system. The correct answer is 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 mitigations that appear as wrong options. Adversarial handling of a leaked secret belongs to Domain 7. This sub-skill covers not committing secrets.

The Domain 3 boundary

Precedence order and hierarchy semantics are tested in Domain 3. They cover how Claude Code consumes settings and CLAUDE.md. A 2.6 question asks about management: what to track, pin, review and keep in parity. If the question is about management practice, an answer that explains precedence is the wrong option, not the right answer.

Exam Traps

Exam Trap

Treating settings.local.json as team-shared or project CLAUDE.md as personal

Project settings.json and project CLAUDE.md are checked in and shared. settings.local.json and CLAUDE.local.md are personal and gitignored. A team baseline placed in a local file is not shared with anybody.

Exam Trap

Switching production to the replacement model first and evaluating afterwards because the retirement date is near

Publicly released models get at least 60 days' notice before retirement, so there is time to evaluate first. Run evals against the candidate, change the pinned identifier through review, then audit for callers still using the old model.

Exam Trap

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

From the 4.6 generation onwards, a dateless identifier is a pinned snapshot. Only the older aliases resolve to a moving target. Record what each environment's identifier resolves to.

Exam Trap

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

An encrypted key in history is still a key in history, and gitignoring takes away a shared file other configuration needs. Move credentials out of versioned files, using a credential helper or runtime environment variables.

Practice Scenario

A project management software company runs a Claude-based status-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 task-template plugin; the model identifiers match everywhere. What is the correct course of action?

Option ACopy 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

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

Option CBackport 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 DAssemble 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

Build Exercise

Audit One Repository's Configuration Surface

Difficulty

35 minutes

What you'll learn

How to enumerate every artefact that affects behaviour 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 artefact that affects behaviour: CLAUDE.md files, settings files, prompt files and templates, the model identifier, and every plugin or MCP capability with its version
Why: The audit that the exam expects 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 tested fact, and applying it to real files is better than 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 changed.
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 is in real use from the first time the pipeline deploys a prompt change 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 updates the pinned identifier, and the usage audit confirming no key still targets the old model
Why: Rehearsing the sequence before a deprecation notice arrives is what makes a 60-day notice period 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