Configuration management

What you’ll be able to do

• Name the four things that must be versioned in a Claude application
• Apply the CLAUDE.md hierarchy so team standards actually reach the team
• Pin model versions and upgrade on purpose
• Gate prompt changes the way you gate code changes

What you need to know

Four artefacts, all of them source

Configuration management here means treating four things as versioned, reviewed source — because all four change behaviour:

1. CLAUDE.md — project instructions
2. settings.json — tool availability and permissions
3. Model version pins — the exact model, not a rolling alias
4. Prompts — versioned, reviewed, and gated by evaluation

Plugin dependencies belong in the same bucket. The failure mode is identical in every case: something that alters behaviour lives outside version control, so a change to it is invisible in the history.

The CLAUDE.md hierarchy

Files layer from broad to specific, and a more specific file overrides a broader one. That's a feature — a monorepo's frontend package can carry conventions its backend package shouldn't — but it's also the source of the most common mistake in the sub-skill.

Pinning, and what it buys

An alias is a convenience that trades control for currency. In development that's usually fine. In production it means an upstream release can change your application's behaviour overnight, with no deploy, no diff, and nothing in your change log to point at.

Pinning makes upgrades an act rather than an event: pin the exact version, run your evaluation set against the candidate version, compare, then move deliberately.

Prompts through the same gate as code

A prompt edit can change output quality more than most code changes, and it typically ships with less scrutiny because it looks like copy. The practice the blueprint names is straightforward — version it, review it, and put an evaluation gate in front of it.

The tell that a team hasn't done this: nobody can say which prompt version produced last month's output.

Key concept

Four artefacts change behaviour — project instructions, permissions config, model pin, and prompts. All four belong in version control, and the model pin plus an eval gate are what keep behaviour from moving without you.

Practice scenario

Build exercise — Audit what isn’t in version control

Beginner · 20 min

What you’ll learn

• Finding behaviour-changing config outside the repo
• Why personal settings silently exclude your team

1. List the four artefacts for your project — CLAUDE.md, tool and permission config, model version reference, prompts — and check which are committed.

   • Why: All four change behaviour. Anything outside version control changes invisibly.
   • You should see: Usually the prompt or the model reference is the one living somewhere it shouldn’t.

2. Check whether your model reference is an exact version or a rolling alias, in production specifically.

   • Why: An alias means an upstream release can change your behaviour with no deploy and nothing in your history to point at.
   • You should see: An exact version string, or a finding.

3. Ask a teammate to show you where the project’s Claude conventions live. If they can’t find them, or they’re in someone’s personal settings, that’s your answer.

   • Why: Conventions the team can’t see don’t exist for the team.
   • You should see: A project-level CLAUDE.md that arrives with a clone — or a gap to fix.

Exam traps

Keeping team conventions in personal settings

It works for one person and silently does not exist for everyone else. Project-level CLAUDE.md, committed to the repo.

Running a rolling model alias in production

Behaviour can move with no deploy and nothing in your history to explain it.

Treating prompt edits as copy changes

They move output quality more than most code changes and deserve the same review and eval gate.

Putting credentials in CLAUDE.md

It is committed to version control by design. Keys belong in a secret manager or environment variable, never in a tracked file.

Sources

• Claude Developer Platform Docs