What Is CLAUDE.md?
CLAUDE.md is Claude Code's memory file. Claude Code reads it when a session starts and treats its contents as standing instructions for the project: how to build and test, which conventions to follow, and what not to touch. It is ordinary Markdown with no frontmatter.
Last verified 2026-11-13 against the vendor documentation. Claude Code is the only agent that treats CLAUDE.md as its primary file, but it is not the only reader: GitHub Copilot's cloud agent, code review and CLI also read CLAUDE.md, and Zed reads it if no higher-priority file exists. See the compatibility table.
Which CLAUDE.md Files Does Claude Code Load?
Claude Code concatenates several files rather than picking one:
~/.claude/CLAUDE.md: user scope, personal preferences for all your projects.CLAUDE.md at the project root and in parent directories: the shared, committed project file.CLAUDE.local.md at the project root: private notes, added to .gitignore, loaded after CLAUDE.md.- CLAUDE.md files in subdirectories, which apply when Claude works in that part of the tree.
How Do @Imports Work in CLAUDE.md?
A line such as @AGENTS.md or @docs/testing.md imports another file. Paths resolve relative to the file that contains the import, imports can nest up to four hops deep, and an @path inside a code span or code block is ignored, so you can still write about imports without triggering them.
This is what makes the AGENTS.md-first pattern work. Claude Code's documentation describes putting an @AGENTS.md import in a CLAUDE.md next to it, and mentions a symlink (ln -s AGENTS.md CLAUDE.md) as an alternative, noting the import is safer on Windows.
# CLAUDE.md
@AGENTS.md
## Claude Code
- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file, so every agent stays in sync.
- Put Claude-only preferences below this line. Personal, uncommitted notes belong in CLAUDE.local.md.
When Does Claude Code Read AGENTS.md Instead?
Recent versions (v2.1.277 and later) can read AGENTS.md directly, but by default only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. The Project instructions setting in /config changes this: claude-md-and-agents-md loads both. Claude Code does not read AGENTS.local.md, AGENTS.override.md or anything under a .agents/ directory.
- If you only use Claude Code, a plain CLAUDE.md is fine.
- If you use several agents, make AGENTS.md the source and keep CLAUDE.md as a thin import.
- If you set claude-md-and-agents-md, do not also import AGENTS.md, or the same text loads twice.
How Long Should CLAUDE.md Be?
Claude Code's documentation recommends targeting under 200 lines per CLAUDE.md file. The whole file is loaded every session, so long files cost tokens on every task and bury the rules that matter. Split specialist material into separate files and import only what is always needed.
What Are the Common CLAUDE.md Mistakes?
- Duplicating AGENTS.md by copy and paste instead of importing it, so the two drift apart.
- Committing personal preferences that belong in CLAUDE.local.md.
- Writing an @import inside backticks and wondering why it did nothing.
- Long persona introductions and motivational text instead of commands and checkable rules.
- No test command, so Claude cannot verify its own changes.
Paste your file into the linter to catch these, or use the CLAUDE.md to AGENTS.md converter to move shared rules into AGENTS.md. The generator produces the thin CLAUDE.md shown above automatically. Compare the two files on CLAUDE.md vs AGENTS.md.
Frequently Asked Questions
Where should CLAUDE.md go?
Put the shared file at the repository root and commit it. Personal preferences for one project go in CLAUDE.local.md next to it, which you add to .gitignore. Preferences for every project go in the CLAUDE.md file inside your home .claude directory.
Can CLAUDE.md import AGENTS.md?
Yes. A line containing @AGENTS.md imports the file. Paths are relative to the importing file and imports can nest four levels deep. This lets AGENTS.md stay the single source of truth while Claude Code still gets a CLAUDE.md.
Is a symlink better than an import?
Both work. A symlink from CLAUDE.md to AGENTS.md means there is literally one file, but symlinks are awkward on Windows. An import line is portable and leaves room for Claude-only notes below it.
Do other tools read CLAUDE.md?
Some do. GitHub Copilot reads CLAUDE.md in its cloud agent, code review and CLI, and Zed reads it when no higher-priority instruction file exists. Cursor and Codex rely on AGENTS.md and their own formats instead.