Task statement 2.6 · Applications and integration

2.6 · Configuration Management

In Shelfwise, the course example, configuration decides which model answers, which stock rules it reads and what Claude Code may do in the repository. Because the service passes setting_sources=[] (2.5), CLAUDE.md and settings files shape only the engineers' Claude Code sessions, and the model ID and prompt version sit in the service's own configuration.

Why it's tested

The tempting setup is to point the service at an alias, so it picks up model improvements without a deploy, and to let each engineer keep the team's Claude Code conventions in their own files. Both fail because what decides an answer or a session then changes, or differs between people, without a reviewed commit, so nobody can say which model and prompt produced last Saturday's answer.

Start hereThree terms this section adds

pinned snapshot
A model ID whose underlying model stays the same for the lifetime of that ID. An updated model ships under a new ID.
alias
A model name that points to whichever snapshot is current, such as Claude Code's sonnet, so it can move without any change on your side.
scope
Who a configuration file applies to: the organisation (managed), you in every project (user), everyone in a repository (project), or you in one repository (local).

KnowledgeCLAUDE.md files as configuration

CLAUDE.md files are instructions that Claude Code reads at the start of every session, in four scopes. A managed policy file from IT applies to everyone on the machine and cannot be excluded. ~/.claude/CLAUDE.md holds your preferences for every project. The project file (CLAUDE.md or .claude/CLAUDE.md) is committed so every clone gets it. CLAUDE.local.md holds your own notes for one project and belongs in .gitignore. Claude Code loads the files in the launch directory and every directory above it, joined from the top down, so none overrides another. If two lines contradict, Claude picks one arbitrarily. Files in subdirectories load only when Claude reads a file there.

Two features keep a long file manageable. An @path import pulls in another file, resolved relative to the importing file. Imports can nest up to four hops, each hop an import inside an import. Imported files load at launch, so an import organises a file without making it cheaper. Rules in .claude/rules/ also load at launch unless their paths frontmatter lists globs, in which case a rule loads only when Claude reads, writes or edits a matching file. As configuration, the committed files are reviewed in pull requests like code, and a periodic pass removes stale and conflicting lines before they cause drift. Because CLAUDE.md only guides (2.5), a rule that must always hold belongs in settings. Shelfwise's repository splits its configuration like this:

shelfwise/
├── CLAUDE.md                     # committed: test and eval commands
├── CLAUDE.local.md               # gitignored: one engineer's own notes
├── .claude/rules/mcp-server.md   # committed; paths: "stock_mcp/**"
├── .claude/settings.json         # committed: permissions, hooks, plugins
└── .claude/settings.local.json   # personal; kept out of git

Knowledgesettings.json: scopes, precedence and merging

Settings files hold what Claude Code enforces: permission rules, hooks, environment variables in an env block, the model, and the enabledPlugins list that 2.5 used to share plugins. Their scopes mirror CLAUDE.md. ~/.claude/settings.json is yours in every project, .claude/settings.json is committed for the team, and .claude/settings.local.json is yours in one project, which Claude Code keeps out of git when it creates the file. Managed settings come from the organisation. When several files set the same key, the highest level wins: managed, then command-line arguments, then local, project and user, except for a few restrictive keys. Most list keys, such as permissions.allow, are another exception, because Claude Code merges the lists from every file, so a personal file can add an entry but cannot remove the team's.

Interactive · which value applies when several settings files set the same key

Two copies of the same settings stack, read from the highest level at the top to the lowest at the bottom: managed, local, project and user. Left, the model key: managed and local leave it unset, project sets sonnet and user sets opus, so the project's sonnet applies and the user's value is overridden. Right, permissions.allow: local, project and user each add one rule, and all three rules apply because lists merge. A single value: model HIGHEST TO LOWEST managed NOT SET local: .claude/settings.local.json NOT SET project: "model": "sonnet" HIGHEST LEVEL THAT SETS IT · APPLIES user: "model": "opus" OVERRIDDEN session model: sonnet ONE VALUE, FROM ONE FILE A list: permissions.allow HIGHEST TO LOWEST managed NOT SET local: "Bash(git log *)" ADDED project: "Bash(pytest *)" ADDED user: "Bash(ls *)" ADDED allowed: all three rules LISTS MERGE ACROSS FILES Command-line arguments sit between managed and local; neither column sets one.

Choose the kind of key that several files set.

A single value: Claude Code takes it from the highest level that sets it. Managed and local leave model unset, so the project's sonnet applies and the user's opus is overridden. A local value would beat both.

A list: Claude Code merges the entries from every file, so the local, project and user allow rules all apply. A personal file can add a rule but cannot remove the team's.

Same four files in each column, highest level at the top. Green applies, amber is overridden, dashed leaves the key unset.

KnowledgeModel version pinning

Every model ID names a pinned snapshot, while an alias is a pointer: in Claude Code, sonnet and opus move to newer models over time. Pinning the full ID in configuration means the same request reaches the same model next month, so you know which model produced an answer, and the eval results you checked still describe production. Pinning does not make a model permanent, because every ID has its own deprecation and retirement dates (2.2), so a planned migration later replaces it.

More precise than the guide. The guide says "model version pinning", but newer model IDs carry no date, and each is still a pinned snapshot, not an alias (as of 2026-10-04). Older models, some still current, have dated IDs plus an alias on the Claude API. Exam answer: pin a specific model ID, never an alias, and move to a new one only after the evals pass.

KnowledgePrompt versioning

Prompt versioning treats a prompt as a released artefact, not a string edited in place. The prompt lives in git, changes through a reviewed pull request, and carries a version that the service reads from configuration and logs with every answer, next to the model ID. An eval result describes one pair, a prompt version and a model ID, so changing either means running the evals again and comparing against the earlier pair as a baseline. Claude Managed Agents (1.2) builds this into the API: each update to an agent's model, system prompt or tools creates a new version, and a session can pin one, so a rollout can be staged.

SkillPinning the pair in Shelfwise's configuration

Shelfwise's model change in 2.2, where an ID edited in code reached every branch at once, shows what this adds:

# 2.2: eval re-run 141/150
# fix: config/release.toml, changed only by pull request
model          = "<replacement's snapshot ID>"   # a full ID, never an alias
prompt_version = "stock-rules-v13"                 # the fixed stock rules
# merge gate: evals 150/150 on exactly this pair, then Leeds for a week

Because the pair changes in one reviewed commit, a rollback is a pull request that restores the previous two lines.

KnowledgePlugin dependencies

A plugin dependency is another plugin that yours needs, such as one whose MCP server your Skill calls, and it goes in the dependencies array of .claude-plugin/plugin.json. An entry is a plugin name, name@marketplace for another marketplace, or an object with a version range such as ~2.1.0. Installing your plugin installs and enables its dependencies at the same scope. Without a range, a dependency moves to each new release its marketplace publishes at the next update, so a renamed tool breaks your plugin for everyone. A range resolves to the highest git tag named <plugin>--v<version> that satisfies it, so the dependency's maintainer must tag releases. When two installed plugins need ranges that do not overlap, the second install fails.

Ask one question: should every clone and every deploy get exactly this value? Yes → commit it to a reviewed file at a fixed version: a model ID, a prompt version, a dependency range, the project CLAUDE.md or .claude/settings.json. No → keep it personal, in ~/.claude/, CLAUDE.local.md or .claude/settings.local.json.
Takeaway
  • CLAUDE.md files add up rather than override; settings files override by level, except list keys, which merge.
  • A model ID is a fixed snapshot and an alias can move, so production names an ID and changes it by reviewed release.
  • Evals vouch for one prompt version on one model ID; change either and run them again.

check yourself

0 / 3 answered

A monorepo keeps its style guide at docs/style.md in the repository root. In her first session in the repository, an engineer starts Claude Code in packages/web/, whose CLAUDE.md has the plain line @docs/style.md. /context lists that CLAUDE.md under Memory files, no approval dialog appeared, and the style rules are never followed.What is the most likely root cause?

Select one.

A legal-intake assistant's prompt lives in git and is deployed several times a week, and each environment sets its model through an environment variable. A client disputes an answer from nine days ago, and nobody can say which prompt and model produced it. Company policy forbids storing client text in logs.Which change most directly lets the team reconstruct the conditions behind any future answer while keeping to the logging policy?

Select one.

A release-notes plugin's Skill calls an MCP tool from the jira-bridge plugin, which has its own git repository and is listed in the same internal marketplace. The coming jira-bridge 3.0 renames that tool. The release-notes team wants users kept on a working 2.x combination with no manual step, and to adopt 3.0 only after testing it.Which TWO changes best achieve this?

Select two.

sources

  1. Claude Code Docs, "How Claude remembers your project": managed, user, project and local CLAUDE.md scopes; managed files cannot be excluded; launch-directory walk, concatenated root-down; subdirectory files on demand; @path imports relative to the importing file, four hops, loaded at launch; contradictions picked arbitrarily; .claude/rules/ and paths frontmatter on Read, Write or Edit; settings for enforcement, CLAUDE.md for guidance. Checked 2026-10-04.
  2. Claude Code Docs, "Settings files and precedence": the four files and managed settings; what each scope is for; the local file kept out of git; precedence managed, command line, local, project, user; lists merge; keys that wait for workspace trust. Checked 2026-10-04.
  3. Claude Platform Docs, "Model IDs and versioning": each ID a pinned version; dateless IDs are snapshots, not aliases; aliases for earlier models point to the newest dated snapshot; each ID has its own deprecation schedule. And Claude Code Docs, "Model configuration": aliases update over time; pin with the full model name. Checked 2026-10-04.
  4. Claude Platform Docs, "Define success criteria and build evaluations": compare performance against a baseline model or earlier version. Checked 2026-10-04.
  5. Claude Platform Docs, "Define your agent" and "Start a session" (Managed Agents, beta): an agent is a versioned configuration of model, system prompt and tools; updates create versions; a session can pin a version to stage rollouts. Checked 2026-10-04.
  6. Claude Code Docs, "Plugin dependencies", "Plugin manifest reference" and "Install and manage plugins": the dependencies array and its entry forms; semantic-version ranges resolved against <plugin>--v<version> tags; unconstrained dependencies follow the marketplace; conflicting ranges fail; install, enable and disable act on dependencies. Checked 2026-10-04.
  7. Shelfwise's repository layout, config/release.toml and the stock-rules-v13 label are this course's example details; the model change, its 141/150 and 150/150 results and the Leeds stage come from 2.2.