Learn · Configuration & workflows · CCAR-F task 3.1
The CLAUDE.md hierarchy
Managed, user, project, local and subdirectory CLAUDE.md files: who shares each, when it loads, and why a teammate misses your rule.
Key ideas
- Levels: managed (IT), user ~/.claude/CLAUDE.md (personal), project ./CLAUDE.md (in Git), local CLAUDE.local.md (gitignored).
- Files from the working directory and its parents load at launch and are combined, not overridden.
- Subdirectory CLAUDE.md files load on demand, when Claude works with files in that folder.
- Team conventions belong in the committed project CLAUDE.md, not your user file.
- @path imports split a big file into modules (up to four hops) but don't reduce context cost.
- Keep files short and concrete; /memory is the first step when a rule seems ignored.
Worked example: A teammate doesn't get your convention
You told Claude to use pnpm in ~/.claude/CLAUDE.md, and a new teammate's sessions keep running npm install. Move the line into ./CLAUDE.md and commit it; keep personal tweaks in ~/.claude or CLAUDE.local.md.
Exam traps
- Putting a team convention in ~/.claude/CLAUDE.md: it is personal and never shared.
- Believing a nearer CLAUDE.md overrides a parent one. They are combined.
- Committing CLAUDE.local.md: it is for your personal notes and should be gitignored.
- Expecting @imports to save context: imported files load with the file that imports them.
Official docs
Practise CCAR-F questions · Next lesson: Path-specific rules