3.1 Configure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization

Key points

1. 1

   Three levels: user (~/.claude/CLAUDE.md, one person, every project), project (CLAUDE.md at the repo root or .claude/CLAUDE.md, shared through version control) and directory-level CLAUDE.md files in subdirectories. CLAUDE.local.md is a personal, gitignored project file.

2. 2

   User-level instructions are never shared via the repository. The classic exam diagnosis: a new teammate does not get the conventions because the lead put them in ~/.claude/CLAUDE.md. Fix by moving them to project level and committing.

3. 3

   Files in the working directory and every directory above it load at launch, concatenated from the filesystem root downward. Subdirectory CLAUDE.md files are discovered lazily and load when Claude reads files in those directories.

4. 4

   Nothing overrides anything: all loaded memory is concatenated. If two files contradict each other Claude may follow either, so remove conflicts in the committed files rather than adding emphasis or using per-machine mechanisms (CLAUDE.local.md, settings.local.json) that teammates and CI never see.

5. 5

   @path/to/file imports another file into the CLAUDE.md that references it (relative to the importing file; recursive to a small depth; paths inside backticks or code blocks are not imported). Use it so each package's CLAUDE.md pulls in only the standards its maintainers know apply.

6. 6

   Imports keep files modular but do not reduce context: imported files are expanded and loaded at launch. To cut what loads, use path-scoped rules instead.

7. 7

   .claude/rules/ holds topic-specific rule files (testing.md, api-conventions.md, deployment.md) as the alternative to a monolithic CLAUDE.md. Files without paths frontmatter load unconditionally; with paths they load only when Claude works on matching files. ~/.claude/rules/ holds personal rules for every project.

8. 8

   Keep CLAUDE.md short (the docs suggest under roughly 200 lines per file). Include commands Claude cannot guess, style rules that differ from defaults, testing instructions, repository etiquette, gotchas; exclude anything derivable from the code, standard language idioms, long tutorials and file-by-file tours. Bloated files cause Claude to ignore the real rules.

9. 9

   Emphasis such as IMPORTANT works only when used on one or two lines. If Claude keeps skipping a rule, the file is probably too long; prune it or convert the rule to a hook for guaranteed enforcement.

10. 10

    /memory lists the CLAUDE.md, CLAUDE.local.md and rules locations across user and project scope and opens them for editing; /context shows what actually loaded this session. Use them to diagnose inconsistent behaviour between developers or sessions. /init generates or improves a starter CLAUDE.md.

11. 11

    CLAUDE.md is advisory context, not enforced configuration. When an action must be blocked or must always happen, use a hook; use CLAUDE.md to describe standards, commands and conventions.

12. 12

    For CI runs, the repository's CLAUDE.md is how project context (testing standards, fixture conventions, review criteria) reaches the non-interactive Claude Code invocation; --bare skips it, so do not use bare mode when that context is needed.

Read the source

• How Claude remembers your project (CLAUDE.md, rules, /memory)
• Best practices for Claude Code