Summary: CLAUDE.md at team scale

Two developers on the same team can get visibly different behavior from the same model on the same repository. The usual cause is not skill and not the model. It is configuration: one teammate wrote the team’s standards into a personal file that nobody else’s sessions ever receive. This lesson reads Claude Code’s configuration layer as an architect would, with one organizing frame: treat configuration as a product. It has users (every teammate, every fresh session), releases (commits), and bugs (drift).

Core ideas

• Claude Code reads persistent instructions from memory files (CLAUDE.md). Where a file lives decides who receives it: a home-directory file reaches only you in every project, a committed project file reaches the whole team, a gitignored local file reaches only you in one project, and subdirectory files load on demand when Claude works with code in those directories. Organizations get a managed tier above all of these.
• Loaded memory files concatenate rather than override. Broad scopes load first and the working directory loads last, but every instruction is present. So the architect’s question is not “which file wins” but “who needs to receive this decision?”
• Memory files can import other files with an at-sign path syntax, up to four hops deep. Imports organize content; they do not reduce what loads into context.
• Memory is a request, not a guarantee. The documentation describes memory as context, not enforced configuration. Style, conventions, and workflow preferences belong there. Rules that must hold every single time belong in settings files and hooks, which the tool enforces regardless of what the model decides. Sorting rules between the two halves is lesson 1’s decide-versus-enforce trade-off, executed in files.
• Settings mirror the memory hierarchy: user, committed project, gitignored local, and managed organization settings that nothing else can override.
• Long memory files decay: everything loads every session, everything competes for attention, and adherence drops. The documentation’s target is under 200 lines per file.
• The rules directory (.claude/rules/) is the cure. Small topic files, committed and shared. A rule with a paths field in its frontmatter loads only when Claude works with files matching those glob patterns. The whole team receives the rule; a session pays for it only when it touches the code the rule governs. That is carry versus fetch, applied to configuration.
• Custom slash commands turn a repeatable workflow into a markdown file. Defined in the project, a command ships with the repository and every teammate gets it; defined in your home directory, it follows you and stays invisible to the team. Current documentation folds commands into skills, and existing command files keep working. An arguments placeholder lets one command file handle variable input.
• Plan mode is a risk decision, not a personality. In plan mode Claude reads files and proposes a plan but makes no edits until you approve. Use direct execution for small, well-scoped changes where a wrong edit is cheap to spot and revert. Use plan mode for large, ambiguous, or sensitive changes, where judgment should stay with the human until the route is approved. The choice itself can be committed as team policy in project memory.
• Configuration drift is “works on my machine” for judgment: the instructions different teammates’ sessions receive have quietly diverged, usually because a team decision lives at user level. Symptoms: conventions that hold only in some people’s pull requests, and onboarding by verbal correction.
• The diagnosis routine: inventory loaded files with the memory command (/memory) on two machines and compare; promote team decisions into project memory or rules files through a pull request; move must-hold rules out of memory entirely, into settings or hooks.
• The payoff of the product frame: configuration that is versioned and reviewed survives the person who wrote it. An architect’s decisions outlive the architect’s attention.

What changes for you

You now hold a small set of questions that make a team’s Claude Code setup legible in minutes. Who receives this instruction, given where the file lives? Is this a request or does it need to be a guarantee? Does this instruction earn a permanent seat in context, or should it load with the files it governs? And for each change: does judgment stay with the human until a plan is approved? When a teammate’s results differ from yours, you no longer shrug; you run the inventory, find the drift, and ship the fix as a pull request. The next lesson turns from configuring the environment to shaping the model’s answers: structured output and schemas.