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.
share
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
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.
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.
.claude/settings.json. No → keep it personal, in ~/.claude/, CLAUDE.local.md or .claude/settings.local.json.- 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.