What CLAUDE.md is and how Claude Code uses it

Last updated October 30, 2026

CLAUDE.md is a Markdown file of instructions that Claude Code reads at the start of every session. Put the rules every session needs in it: build and test commands, code style, project layout and things to avoid. Claude Code loads it automatically, so you don't have to repeat those rules in each conversation.

Where Claude Code looks for CLAUDE.md

Claude Code reads CLAUDE.md files from several places. Each one has a different reach:

• Your project: ./CLAUDE.md or ./.claude/CLAUDE.md. Commit it, and everyone who works in the repository gets the same instructions.
• Your own projects: ~/.claude/CLAUDE.md applies to every project on your computer, for you only.
• Just you, in one project: ./CLAUDE.local.md. Add it to .gitignore so it stays out of the repository.
• Your organization: a managed policy file that an administrator installs, for example /Library/Application Support/ClaudeCode/CLAUDE.md on a Mac or /etc/claude-code/CLAUDE.md on Linux.

Topic files in .claude/rules/ work like extra CLAUDE.md files. A rule file can also name the paths it applies to, so it loads only when Claude works on matching files.

How CLAUDE.md files load

When a session starts, Claude Code reads the CLAUDE.md and CLAUDE.local.md files in the folder you started in and in every folder above it. The files are added together, not replaced: they are read from the top of the file system down, so the file closest to your folder comes last.

A CLAUDE.md in a subfolder below your starting folder loads later, the first time Claude reads or edits a file in that subfolder.

To see which files loaded, run /context and look under "Memory files".

After /compact, Claude Code reads the project's root CLAUDE.md again from disk. Instructions you gave only in the conversation are not kept.

Create and edit CLAUDE.md

1. Run /init in Claude Code. It reads your codebase and writes a starting CLAUDE.md with build commands, test steps and conventions. If a CLAUDE.md already exists, it suggests changes instead of overwriting it.
2. Run /memory to open any of your CLAUDE.md files in your editor. It also lists files that don't exist yet; choose one to create it.
3. Or ask Claude: "add this to CLAUDE.md". Asking it to "remember" something saves to auto memory instead (see below).

Import other files

A CLAUDE.md can pull in other files with @path/to/file, for example @docs/testing.md or @~/.claude/my-preferences.md. Relative paths start from the file that has the import. Imports can nest up to four levels deep.

Imports help you organize, but they don't save context: an imported file loads with the CLAUDE.md that imports it.

How long CLAUDE.md should be

Claude Code's documentation says to aim for under 200 lines per CLAUDE.md file, because longer files use more context and are followed less closely. Claude Code shows a warning at startup and in /status when a file is longer than that.

To keep it short:

• Keep only rules that apply to most tasks.
• Move rules for one part of the code into .claude/rules/ with a paths setting, or into a CLAUDE.md in that subfolder.
• Move facts that only some tasks need, such as past decisions, out of the file and into something the agent searches. See CLAUDE.md and AGENTS.md vs a memory server.

CLAUDE.md vs auto memory

Claude Code has two kinds of memory:

• CLAUDE.md is written by you and loads in full in every session.
• Auto memory is written by Claude. It keeps notes in ~/.claude/projects/<project>/memory/, with an index file, MEMORY.md. The first 200 lines or 25 KB of MEMORY.md load at the start of each session, and Claude reads the other notes when it needs them.

Auto memory stays on one computer. Turn it off with /memory, with "autoMemoryEnabled": false in settings, or with the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

CLAUDE.md and AGENTS.md

AGENTS.md is the instruction file that Codex and many other coding agents read. Claude Code, from version 2.1.277, reads a project's AGENTS.md when the project has no CLAUDE.md. If both exist, it reads CLAUDE.md only, unless you change "Project instructions" in /config.

To use one file for both, put @AGENTS.md at the top of CLAUDE.md and add anything specific to Claude Code below it. More in What AGENTS.md is.

Frequently asked questions

Where is the CLAUDE.md file?

There can be several. The project file is CLAUDE.md or .claude/CLAUDE.md in the repository. Your personal file for all projects is ~/.claude/CLAUDE.md. /memory lists the ones Claude Code uses.

Does CLAUDE.md load in every session?

Yes. The CLAUDE.md files in your starting folder and the folders above it load when the session starts. Files in subfolders load when Claude first works in that subfolder.

Is CLAUDE.md enforced?

No. Claude Code reads it as instructions, not as settings it must obey. To block an action no matter what, use a hook or a permission rule in settings.

Should I commit CLAUDE.md to git?

Commit the project CLAUDE.md so the whole team shares it. Keep personal notes in CLAUDE.local.md, which you add to .gitignore, or in ~/.claude/CLAUDE.md.

Can Claude Code use memory outside CLAUDE.md?

Yes. Besides auto memory, you can connect an MCP memory server, which agents search instead of loading in full. See how to give Claude Code memory between sessions.

Sources

Checked on October 30, 2026:

• How Claude remembers your project, Claude Code documentation
• Commands, Claude Code documentation