CLAUDE.md is a plain markdown file of instructions that you (or your team) write once, and that Claude Code reads at the start of every session. It is how you stop re-explaining the same build commands and house rules in every new chat.
What it is
A built-in Claude Code feature. Claude Code looks for files named CLAUDE.md in a few known places and puts their text into the session’s context window. It is one of two ways knowledge carries over between sessions; the other is auto memory, the notes Claude writes for itself.
It is context, not configuration. The text arrives as a message after the system prompt, and Claude tries to follow it, but nothing enforces it. Anything that must never happen belongs in a hook or a permission rule instead.
Where the files live
| Scope | Location | For |
|---|---|---|
| Managed policy | macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux and WSL /etc/claude-code/CLAUDE.md | Organization-wide rules, deployed by IT |
| User | ~/.claude/CLAUDE.md | Your personal preferences, in every project |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Team rules, committed to the repo |
| Local | ./CLAUDE.local.md | Your personal rules for one project; add it to .gitignore |
How they combine
The files do not override each other; Claude Code concatenates them. It loads every CLAUDE.md and CLAUDE.local.md from the directory you started Claude in and from every directory above it, ordered from the filesystem root down. So the file in your working directory lands in the context last, after the ones from parent directories, and in each directory CLAUDE.local.md comes after CLAUDE.md.
A CLAUDE.md in a subdirectory below your working directory does not load at startup. It loads the first time Claude reads, writes or edits a file in that subdirectory.
What else plugs into it
- Imports.
@path/to/fileanywhere in a CLAUDE.md pulls that file into the context at startup. Paths resolve relative to the file that contains the import, not the working directory, and imports can nest up to four levels deep. A path inside backticks (`@README`) stays plain text. - Rules. Markdown files in
.claude/rules/, one topic per file, found recursively. A rule without frontmatter loads at startup like CLAUDE.md. A rule with apaths:list of globs in its frontmatter loads only when Claude reads, writes or edits a file that matches. Personal rules for every project go in~/.claude/rules/. - AGENTS.md. The instruction file other coding agents use. By default Claude Code reads it only when there is no
CLAUDE.mdorCLAUDE.local.mdin the working directory or above it. To use both, start your CLAUDE.md with@AGENTS.md, or set Project instructions toclaude-md-and-agents-mdin/config. - HTML comments. Block-level
<!-- ... -->comments are stripped before the text reaches the context, so notes for human maintainers cost no tokens.
What problem it solves
Every session starts with an empty context. Without CLAUDE.md you type “run npm run typecheck before you say you’re done” or “we use pnpm” again and again, and the agent repeats the same mistakes. Rules typed into chat also fade: when the context fills up and gets compacted, early messages can be summarized away, while the project-root CLAUDE.md is re-read from disk after compaction.
How to try it
- In your project, run
/init. Claude explores the codebase and writes a starting CLAUDE.md with build and test commands and the conventions it found. If a CLAUDE.md already exists, it suggests improvements instead of overwriting it. - For a guided version, set
CLAUDE_CODE_NEW_INIT=1first./initthen asks which pieces to set up (CLAUDE.md files, skills, hooks), asks follow-up questions, and shows a proposal before it writes anything. - Start a new session and run
/context. Your files should be listed under Memory files. - Use
/memoryto see every instruction file Claude Code knows about and open one in your editor.
From there, add what Claude could not discover on its own, and cut what it can. Writing and maintaining CLAUDE.md covers what belongs in it.
Usage example
A made-up TypeScript repo with a React app in web/ and a Node API in server/.
Frontend
The project CLAUDE.md holds what applies everywhere, including the frontend rules every change touches:
@AGENTS.md
## Commands
- `npm run typecheck && npm test` after every change
- `npm run dev` starts web and server together
## Conventions
- Strict TypeScript, no `any`; types from `const` arrays, not manual unions
- No hardcoded UI strings, only `t('key')`
- Never edit generated files in `src/gen/`
## Gotchas
- Server tests need a local Postgres: `docker compose up db`The @AGENTS.md line keeps one shared file for teammates on other agents, and still lets Claude read it.
Backend
Rules that only matter for the API go in .claude/rules/api.md, scoped with paths:, so they enter the context only when Claude opens or edits a server file:
---
paths:
- "server/**/*.ts"
---
# API rules
- Validate every request body at the route
- Throw typed errors, never a raw `Error`
- Route handlers stay thin: parse, call one service, respondA session spent on the React app never loads these lines.
Who it’s for and when
Anyone using Claude Code on a project for more than one session. Start one as soon as you catch yourself correcting the same thing twice. Use the user-level file for habits that follow you everywhere, and the local file or ~/.claude/ for anything that should not land in a shared repo.
Gotchas
- Imports do not save context. They organize a long file, but imported files load in full at startup. Only rules with
paths:(and subdirectory CLAUDE.md files) load later. - Mid-session edits do not apply. Claude keeps the version it loaded at session start until
/clear,/compactor a restart. See Prompt caching. - Advice, not a guarantee. Vague or contradictory instructions get followed loosely; if two rules conflict, Claude may pick either. Enforce hard limits with hooks or permissions.
CLAUDE.local.mdhidesAGENTS.md. Adding a local file to a project that relies onAGENTS.mdstops Claude readingAGENTS.md, unless Project instructions is set toclaude-md-and-agents-md.- It costs context. Everything loaded at startup sits in every session’s context. The docs suggest under 200 lines per file; Claude Code warns at startup when a file is over that length.