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.

Last updated
By
Published
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.

On this page Why it mattersHow each tool does itQuestions

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

  1. The rule

    You say: we use pnpm, never npm

    Typed into the conversation, early in the session.

  2. The session

    The window fills and compacts

    Older material is summarised, and a constraint stated early may not survive the summary.

  3. 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

  1. The rule

    A line in the file: we use pnpm, never npm or yarn

    Written as concretely as a prompt, committed and reviewed like code.

  2. The load

    Claude Code loads it at launch

    /context lists it under Memory files; a file missing from that list does not exist for Claude.

  3. 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.

  4. 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.deny rule does.

CLAUDE.md content arrives as a user message after the system prompt. That is the mechanical reason it is advisory. Source: Claude Code memory guide, Claude Code 2.1.283, 2026-09-26.

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.

Does this page answer your questions?

One tap, no sign-in.

not at all fully

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.