CLAUDE.md best practices with @imports
Where the file lives, how to keep it short, and how imports and rules keep it organised.
CLAUDE.md is the file Claude Code reads at the start of every session to learn how your project works and how you want it to behave. A good one saves you from repeating yourself. A bad one, long, stale or contradictory, quietly makes every session worse. This guide covers where the file lives, how to keep it short with @ imports, and what belongs in it.
Where CLAUDE.md files live
Claude Code loads instructions from several places, in order from the broadest scope to the most specific:
- A managed policy file for an organisation (on Linux,
/etc/claude-code/CLAUDE.md). - Your personal file,
~/.claude/CLAUDE.md, for preferences that apply to every project. - The project file,
./CLAUDE.mdor./.claude/CLAUDE.md, which you commit so the whole team shares it. CLAUDE.local.mdfor your own notes about a project that you do not commit.
CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the directory you start Claude Code in are loaded at launch, so a repository-level file also applies when you start inside a subfolder. Run /init in a project to have Claude draft a first file from the codebase, then edit it by hand.
Keep it short
The docs recommend a target of under 200 lines per CLAUDE.md file. The reason is practical: the file is read into the context window every session, so every line costs attention and tokens, and a long file makes instructions compete with each other. A useful test for each line: would Claude get it wrong without it? If it would not, delete the line. Typical keepers:
- Commands Claude cannot guess: how to run the tests, how to build, how to start the dev server.
- Rules that differ from the default: "never commit to main", "use the staging database for tests".
- Pointers to where things live, when the layout is not obvious.
Typical cuts: explanations of what the code does (Claude can read it), long style guides that a formatter already enforces, and anything that was true once.
Split with @imports
When the file grows, do not paste everything into it. CLAUDE.md files can import other files with the @path/to/import syntax. Imported files are expanded and loaded into context alongside the file that imports them.
# Project
Run tests with `npm test`. Never commit to main.
@docs/architecture.md
@docs/deploy-rules.md
@~/.claude/my-preferences.md
Three details to know:
- Relative paths resolve relative to the file that contains the import, not to the directory you started Claude Code in. Absolute paths and paths starting with
~work too. - Imported files can import further files, up to a maximum depth of four hops. Past that, imports are not followed. Keep the tree shallow.
- Imports do not make the content smaller. They make it organised. All imported text still loads at launch, so the 200-line target is about the total, not only the top file.
Imports are useful for two things: sharing one file between several projects (a common deployment rule, kept in one place) and keeping private preferences out of a committed file by importing them from your home directory.
Rules that load only when needed
For instructions that matter only for certain files, use the .claude/rules/ directory instead of growing CLAUDE.md. A rule file can carry a paths field in its frontmatter. A path-scoped rule loads when Claude uses the Read, Write or Edit tool on a matching file, so the API rules cost nothing while Claude works on the frontend. paths is the only frontmatter field Claude Code reads from a rule; other fields are ignored without an error.
---
paths:
- "src/api/**/*.ts"
---
All endpoints validate input with the shared schema helpers.
Return errors as { "error": "..." } with the right status code.
A starting template
# Project name
One sentence on what this is.
## Commands
- Test: `npm test`
- Build: `npm run build`
## Rules
- Never commit to main; open a pull request.
- Ask before deleting files or running destructive commands.
- Run the tests before you say a task is done.
## More
@docs/architecture.md
Instructions are requests, hooks are locks
Claude follows CLAUDE.md closely, but it is guidance, not enforcement. For rules that must never be broken, such as destructive commands, use a hook or a deny rule in settings, which the program enforces. Keep CLAUDE.md for conventions and context, and review it every few weeks: delete what is stale, merge duplicates, and move bulky reference material into an import.