Practice: CLAUDE.md at team scale
Self-check
Section titled “Self-check”Six short questions. Answer each in your head before opening the collapsible. Active retrieval is where the learning sticks.
1. Name the four everyday memory file locations and the audience each one reaches.
Show answer
User memory in your home directory reaches you in every project. Project memory at the repository root is committed, so it reaches the whole team. Local project memory is a gitignored file that reaches only you, in that one project. Subdirectory memory files load on demand and reach whoever is working with files in that directory. Organizations add a fifth, managed tier above all of these.
2. Two teammates get consistently different Claude behavior in the same repository. What is the most likely cause, and what is the first diagnostic step?
Show answer
Configuration drift: instructions living at the wrong level, most often team decisions written into one person’s user-level memory file. First step: both teammates run the memory command (/memory) in a session, which lists every memory and rules file currently loaded, and compare the lists. Drift shows up as instructions present on one machine and absent on the other.
3. When several memory files load in one session, does the closest file override the broader ones?
Show answer
No. Loaded files are concatenated into context rather than overriding each other. Broad scopes load first and files closest to the working directory load last, but every loaded instruction is present. That is why conflicting instructions across files are a real problem: the model may weigh either one.
4. The team agrees that nothing may ever be pushed directly to the main branch. Where does that rule live, and why not in a memory file?
Show answer
In the enforcement half of the configuration layer: permission rules in settings files, or a hook. Memory files are context, not enforced configuration; instructions in them are followed almost every time, and a must-hold rule cannot tolerate almost. This is lesson 1’s decide-versus-enforce trade-off, executed in files.
5. What does a paths field in a rules file’s frontmatter do, and which lesson 1 trade-off is it applying?
Show answer
It scopes the rule with glob patterns, so the rule loads only when Claude works with files matching those patterns instead of loading in every session. The whole team still receives the rule through version control, but a session pays its context cost only when it touches the governed code. That is carry versus fetch, applied to configuration.
6. When does a change call for plan mode rather than direct execution?
Show answer
When the change is large, ambiguous, or in a sensitive area (many files, an unclear approach, or code like billing, auth, or migrations). In plan mode, Claude reads files and proposes a plan but makes no edits until you approve, so judgment stays with the human until the route is agreed. Small, well-scoped changes are cheaper to execute directly and review as a diff afterward.
Try it yourself
Section titled “Try it yourself”Audit exercise: find your own drift.
If you use Claude Code, run this audit on a real project. It takes about twenty minutes.
- Open a session in the project and run the memory command (/memory). Write down every file it lists, and which tier each one belongs to: user, project, local, or rules.
- Read your user-level memory file line by line. For each instruction, ask the audience question: would a new teammate need this to be productive? Mark every line where the answer is yes. Those are team decisions living at the wrong level.
- Promote one of them. Move it into project memory or, if it only governs part of the codebase, into a path-scoped rules file. Commit it on a branch and open a pull request, even if you work alone: the point is treating configuration as a reviewable product.
- Find one rule in any memory file that must hold every single time. Note where it would have to move (settings or a hook) to become a guarantee instead of a request.
- Bonus: pick a workflow you repeat by typing the same instructions into chat, and turn it into a project slash command with an arguments placeholder.
If you do not use Claude Code yet, do the paper version: take any layered configuration you know (editor settings, linter config, CI) and sort five of its entries into personal, project, and organization scope, noting which ones are requests and which are enforced.
Keep your audit notes. The capstone lesson asks you to design a team’s whole configuration surface, and this inventory is its raw material.
Flashcards
Section titled “Flashcards”Q. What single question does the memory hierarchy turn into architecture?
Who needs to receive this decision? Personal preference: home directory. Team decision: committed project file. Machine-only detail: gitignored local file.
Q. Who receives an instruction written in the user-level memory file?
Only you, in every project you open. No teammate’s session ever loads it, which is how team standards written there become drift.
Q. Do memory files override each other when several load at once?
No. They are concatenated into context, broadest scope first, working directory last. Every loaded instruction is present, so conflicts must be removed, not out-ranked.
Q. Memory versus settings: what is the split?
Memory is a request: context that shapes judgment. Settings and hooks are guarantees: enforced by the tool no matter what the model decides. Must-hold rules go in settings; everything else can be prose.
Q. What does path scoping in a rules file buy a team?
The whole team receives the rule through version control, but it loads only when a session works with files matching its glob patterns. Carry versus fetch, applied to configuration.
Q. Why does the documentation advise keeping a memory file under about 200 lines?
Every line loads into every session and competes for the model’s attention, so adherence drops as the file grows. Split topics into rules files and move procedures into commands.
Q. Project slash command versus personal slash command: what is the difference?
A command defined in the project ships with the repository, so every teammate gets it and can review it. A command in your home directory follows you across projects and is invisible to the team.
Q. What is plan mode?
A mode where Claude reads files and proposes a plan but makes no edits until you approve. Enter it mid-session with a keyboard shortcut or start a session in it with a launch flag.
Q. When is plan mode the right call, and when is it just tax?
Right call: large, ambiguous, or sensitive changes, where judgment should stay with the human until the route is approved. Tax: small, well-scoped changes that are cheaper to execute directly and review as a diff.
Q. What is configuration drift, and what is the fix?
Works on my machine, for judgment: teammates’ sessions receive different instructions, usually because team decisions live at user level. Inventory loaded files with the memory command, then promote team decisions into the repository through a pull request.