What is CLAUDE.md?
CLAUDE.md is Claude Code’s instruction file. It loads at session start from the project root and ~/.claude/CLAUDE.md, and from a subdirectory when the agent works there, and holds the commands, conventions and pitfalls Claude cannot infer from the code. /init drafts one, /memory edits it, and @path/to/file imports another file. It guides the model and enforces nothing.
- In Polish
- CLAUDE.md
- First set up at
- Level 2, free guide
- Also searched as
- CLAUDE.md file, Claude Code memory file
$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.
Why it matters.
Without it, two sessions on the same repository can behave differently because only one of them was told the conventions: the model is the same, the context is not. With it, the commands and conventions load every time and go through review like code. It is still advice: what must happen every time belongs in a hook or a permission rule.
One rule, said two ways
The same instruction, typed into the chat and written into the file, carried across a compaction.
- Advice the model weighs
- A mechanism that runs
- What you can rely on
Said once, in the chat Not kept
-
The rule
You say: we use pnpm, never npm
Typed into the conversation, early in the session.
-
The session
The window fills and compacts
Older material is summarised, and a constraint stated early may not survive the summary.
-
What you can rely on
Nothing: it only lived in the chat
Instructions you gave only in the chat are gone after
/compact.
Written in CLAUDE.md Re-read from disk
-
The rule
A line in the file:
we use pnpm, never npm or yarnWritten as concretely as a prompt, committed and reviewed like code.
-
The load
Claude Code loads it at launch
/contextlists it under Memory files; a file missing from that list does not exist for Claude. -
The compaction
The project-root file is re-read from disk
Subdirectory files and path-scoped rules come back when Claude next reads a matching file.
-
What you can rely on
The text is back in context
Claude may still weigh it against other instructions: the file guides and never enforces. A hook or a
permissions.denyrule does.
How each tool does it.
Cursor, Claude Code and Codex each name this their own way. Each note carries the date it was checked.
Cursor
Applies instructions through Rules in .cursor/rules/. Cursor’s docs say it reads CLAUDE.md the same way it reads AGENTS.md and always applies it; the agent runtime in @cursor/sdk 1.0.32 (checked 2026-09-26) loads CLAUDE.md and CLAUDE.local.md only when third-party configuration loading is on, while it loads AGENTS.md unconditionally.
The two sources disagree on CLAUDE.md, so if your team also uses Claude Code, assume it costs tokens on every Cursor request. To check your build, ask a new Agent chat which instruction files it loaded, and repeat the question after every Cursor update.
Cursor token management guide, 2026-10-12
Claude Code
Loaded at launch from the project root and ~/.claude/, and from a subdirectory when Claude reads a file there; the files add up and none overrides another.
Older guides say to start a message with # to save a memory. Claude Code removed that shortcut in v2.0.70 (2025-12-15): ask Claude to edit CLAUDE.md, or open the file with /memory.
Project initialization guide, Claude Code 2.1.283, 2026-09-26
Codex
Reads AGENTS.md natively, and /init creates one.
Codex combines one global file from ~/.codex/ with at most one project file per directory, from the repository root down, so deeper files land later. A project you mark untrusted supplies no project files.
Codex AGENTS.md guide, Codex CLI 0.157.1, 2026-09-26
Questions about CLAUDE.md.
Where should CLAUDE.md live?
In the project root (./CLAUDE.md or ./.claude/CLAUDE.md) for rules the team shares, in ~/.claude/CLAUDE.md for your preferences in every project, and in CLAUDE.local.md for notes about one checkout (add that file to .gitignore yourself). A CLAUDE.md in a subdirectory loads when Claude reads a file there. The files add up and none overrides another, so you fix a conflict by deleting a rule.
Is CLAUDE.md the same as AGENTS.md?
Same job, different tools: Claude Code reads CLAUDE.md and Codex reads AGENTS.md. From v2.1.277 (both release channels on 2026-10-12) Claude Code also reads AGENTS.md, but by default only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists, so adding a CLAUDE.md silently hides your AGENTS.md. Keep the rules in AGENTS.md and make CLAUDE.md import it with @AGENTS.md, or set Project instructions in /config to claude-md-and-agents-md to load both.
Does CLAUDE.md enforce anything?
No. Its content arrives as a user message after the system prompt, so it guides Claude and never enforces. Anything that must happen every time, such as running the linter after an edit or never touching migrations/, belongs in a hook or a permissions.deny rule.
Does Cursor read CLAUDE.md?
Yes, according to Cursor’s docs (checked 2026-10-12): it reads CLAUDE.md files the same way it reads AGENTS.md and always applies them. The agent runtime in @cursor/sdk 1.0.32 (checked 2026-09-26) is stricter: it treats CLAUDE.md and CLAUDE.local.md as instructions only when third-party configuration loading is on, and loads AGENTS.md unconditionally. Ask a new Agent chat which instruction files it loaded.
Keep reading.
The guides that go deeper, and the terms and comparisons next to this one.
In the docs
Does this page answer your questions?
One tap, no sign-in.
What are you here for?
What is holding you back?
How does it read?
Thanks. If you left an email, Michał will reply.
Answering your questions?
One tap each. Close whenever you like.
no sign-in
Read the guides in the same words.
Open every guide with the Toolkit. Each term is defined once here, and the guides use it the same way.
$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.
Michał replies, not a bot. The address is used for this reply only.