Definition
CLAUDE.md
CLAUDE.md is a markdown file Claude Code reads automatically for project-specific context. It sits at the project root, or in subdirectories for scoped rules, and defines coding standards, common commands, architecture notes and any instruction the agent should always follow. It is created with /init and updated with /memory or the # shortcut.
Why it matters
Without it, every session starts by re-explaining the project. With it, the standards, the commands and the architecture notes are already loaded — which is the difference between an agent that guesses your conventions and one that follows them.
How each tool handles it
- Cursor
- Uses
.cursor/rulesand.cursorignoreinstead. - Claude Code
- The native format, read hierarchically from the root down.
- Codex
- Uses AGENTS.md instead, to the same purpose.
Frequently asked questions
Where should CLAUDE.md live?
At the project root for project-wide rules, and in subdirectories when a rule should apply only to part of the repository. Claude Code reads the hierarchy, so a nested file narrows scope rather than replacing the root one.
Is CLAUDE.md the same as AGENTS.md?
Same purpose, different convention. AGENTS.md is recognised by Codex and increasingly by other tools; CLAUDE.md is what Claude Code reads. Projects used by both commonly keep both files.
Does Cursor read CLAUDE.md?
No. Cursor reads .cursor/rules and .cursorignore; Codex reads AGENTS.md. The three conventions do the same job with different filenames, which is why a repository worked on by several agents usually carries more than one.