A new hire says Claude Code ignores your team's conventions, though it works for everyone else. The conventions are in the tech lead's ~/.claude/CLAUDE.md. What is the fix?
Why A is the answer
Move the conventions into the project CLAUDE.md under version control
User-level config applies to one person and never travels with the repo. Team standards belong in project-level configuration.
In detail
- Claude Code loads CLAUDE.md from several scopes: managed policy, user, project and local. They are concatenated into context rather than overriding each other.
- The user file at ~/.claude/CLAUDE.md belongs to one person on one machine. It works for the tech lead and for nobody else, which explains the symptom.
- The project file is committed, so everyone who clones the repository gets it, and changes go through normal review.
- Personal preferences can stay in the user file. Team rules belong in the repository.
Use case
An illustrative scenario, not a real incident.
A tech lead keeps "use the repository pattern" in a personal file, so their sessions follow it and a new hire's do not. Moving it to the project CLAUDE.md gives everyone the rule on their next pull.
See it in different ways
flowchart TD A["Managed policy"] --> E["Session context"] B["User file"] --> E C["Project file, in git"] --> E D["Local file, personal"] --> E
flowchart TD A["Tech lead's ~/.claude/CLAUDE.md"] --> B["Tech lead only"] C["Project CLAUDE.md in git"] --> D["Every developer"] C --> E["CI runs"]
mindmap
root(("CLAUDE.md files"))
n1["Project file"]
n2["Committed to Git"]
n3["Whole team"]
n4["User file"]
n5["One person"]
n6["Every project"]Key point: If the whole team needs it, commit it.
Why the other options are wrong
- B. Ask the new hire to copy the tech lead's file into their own home directory
- This works once, then the copies drift apart, and every new hire repeats the step.
- C. Add the rules to each developer's shell profile so they load at startup
- A shell profile does not feed conventions to Claude Code, and it still lives outside the repository.
- D. Run /compact at the start of each session so the rules stay in context
- /compact manages the conversation. It cannot add rules that were never loaded.