What is CLAUDE.md? Claude Code project instructions

Nov 5, 2026

CLAUDE.md is the Markdown file of project instructions Claude Code loads at the start of a session. How Codex, Cursor and Grok Build treat that same filename.

CLAUDE.md is a Markdown file of instructions you write for Claude Code. Claude reads it at the start of every session and treats it as context, not as a setting that can block a command. You use it for build commands, conventions, and the mistakes you are tired of repeating.

What is an AGENTS.md file is the guide for the shared instruction file that Codex, Cursor and Grok Build read by default. This entry is the Claude Code filename, and what the other three tools do when a repo has one.

How CLAUDE.md works

Claude Code looks for the file in a few places and concatenates what it finds, from the broader scope to the more specific. A line in the project file does not erase a line in your user file. Both are in the prompt. Instructions closer to where you launched Claude are read later.

The file is delivered as a user message after the system prompt. It is not part of the system prompt. A project-root CLAUDE.md is re-read from disk after compaction. Instructions you only typed in the chat may not survive that summary.

Claude Code can also read AGENTS.md. By default it does that only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or any parent. Your user file and the managed file do not count toward that check. If both a project CLAUDE.md and an AGENTS.md exist, Claude reads the CLAUDE.md files only, until you change Project instructions.

CLAUDE.md in each tool

	Claude Code	Codex	Cursor	Grok Build
Reads `CLAUDE.md` by default	Yes	No. Add the filename to `project_doc_fallback_filenames` if you want it	Not documented on the rules page	Yes, along with `Claude.md` and `CLAUDE.local.md`
File it reads without setup	`CLAUDE.md`, or `AGENTS.md` when no Claude file is present	`AGENTS.md`, then `AGENTS.override.md`	`AGENTS.md` and `.cursor/rules/*.mdc`	`AGENTS.md` and `CLAUDE.md` in the same walk
Personal file	`~/.claude/CLAUDE.md`	`~/.codex/AGENTS.md`	User Rules in Customize	Global rules in `~/.grok/`
On a conflict	Files are concatenated, closer to the launch directory last	One file per directory. Deeper files are concatenated later	Nested `AGENTS.md` files combine, and the more specific file wins	Deeper files take precedence

Claude Code

Put project instructions in ./CLAUDE.md or ./.claude/CLAUDE.md. Personal instructions for every project go in ~/.claude/CLAUDE.md. An organization can deploy a managed file, on macOS at /Library/Application Support/ClaudeCode/CLAUDE.md. CLAUDE.local.md in the project is for notes you do not commit. Add it to .gitignore.

Claude also walks parent directories at launch. Files under the working directory wait until Claude reads, writes, or edits a file there, including a Bash read such as cat or head on a single file. @path imports another file into the same context. An import inside a code span or a fenced code block is left as text. Block HTML comments are stripped before the file is injected, so a note for yourself there does not cost context. Comments inside code blocks stay.

/init drafts a starter from the codebase. If a CLAUDE.md already exists, /init suggests improvements instead of replacing the file. The memory docs say to keep each file under about 200 lines and to write lines you could check. A long file uses more of the context window and is followed less reliably. /memory lists the loaded files. See How Claude remembers your project.

To read CLAUDE.md and AGENTS.md together, set Project instructions to claude-md-and-agents-md in /config. The default is claude-md-or-agents-md.

OpenAI Codex

Codex reads AGENTS.override.md if that file exists and is non-empty, otherwise AGENTS.md. It does this in ~/.codex, then from the project root down to the working directory, one file per directory. The combined project instructions stop at project_doc_max_bytes, 32 KiB by default.

CLAUDE.md is not on that list. The fallback setting is how you add another filename. This is the example from the docs, with CLAUDE.md added the same way:

project_doc_fallback_filenames = ["CLAUDE.md"]

Codex then checks each directory for AGENTS.override.md, then AGENTS.md, then CLAUDE.md, and still keeps at most one file per directory. The combined project files still stop at the default 32 KiB. The docs’ example raises that cap with project_doc_max_bytes = 65536. Restart Codex after you change the config. The instruction chain is rebuilt when a run starts. See AGENTS.md in the Codex docs.

Cursor

Cursor’s rules page documents AGENTS.md in the project root and in subdirectories, and .mdc files in .cursor/rules. A plain .md file in .cursor/rules is ignored. The page does not mention CLAUDE.md.

If the repo already has a CLAUDE.md and you want Cursor to load those instructions, put them in AGENTS.md or in a project rule. See the Cursor rules docs.

Grok Build

Grok walks from the repo root down to the working directory and reads AGENTS.md, Agents.md, AGENT.md, CLAUDE.md, Claude.md and CLAUDE.local.md, plus every *.md file in .grok/rules/, .claude/rules/ and .cursor/rules/. Deeper files win on a conflict. Files that .gitignore ignores are skipped, so a gitignored CLAUDE.local.md stays out of the prompt.

There is no size cap. The page still says short, specific instructions are followed more reliably than long ones. grok inspect lists each file it found, with the path and an approximate token count. See AGENTS.md in the Grok Build docs.

Details checked against each vendor’s documentation in November 2026.

A real example

A project CLAUDE.md for this site, short enough to check:

# flaviocopes.com

Astro site. Posts are Markdown files in src/posts/.

## Commands

- npm run dev starts the local site
- npm run build builds the production site

## Boundaries

- Do not edit files under src/course-content/.
- Do not add a root functions/_middleware.js.

Claude Code loads that file from the repository root. Grok Build loads it too, as long as it is not gitignored. Codex loads it only after CLAUDE.md is in project_doc_fallback_filenames, and only in directories where no AGENTS.md or AGENTS.override.md won. Cursor’s documented path for the same rules is AGENTS.md.

/init in Claude Code can draft the commands section from the repo. Read it before you keep it. A generated test command that the project does not have is worse than no line.

When to use CLAUDE.md

Use it for facts that should be true on the next session: how to build, which directory not to touch, a convention a formatter does not enforce. The memory docs’ test is whether you would otherwise type the same explanation again.

Skip it for a procedure that only matters for one kind of task. That is an agent skill. Skip it for a plan of the change you are making today. That is plan mode, or the prompt in front of you.

If the repo is already set up with AGENTS.md and several agents read it, adding a CLAUDE.md changes Claude Code’s default: it stops reading AGENTS.md until you set claude-md-and-agents-md or import AGENTS.md from CLAUDE.md with @AGENTS.md.

Pitfalls

The files are context. They do not block a tool. Two contradictory lines can go either way, and the memory docs say Claude may pick one arbitrarily. A hook is what rejects a command.

CLAUDE.local.md counts as a Claude file. Adding one to a project that relied on AGENTS.md makes Claude Code stop reading AGENTS.md for you, even when the committed tree has no CLAUDE.md.

Imports do not save context. The imported file is loaded with the CLAUDE.md that points at it. A file past about 200 lines is the size the memory docs tell you to split, moving the local notes into path-scoped rules under .claude/rules/.

Grok skips gitignored instruction files. A CLAUDE.local.md you gitignored on purpose for Claude Code is invisible to Grok as well.

Cursor’s rules page, checked in November 2026, does not say it reads CLAUDE.md. A repo that only has that file is not a Cursor rules setup until the same instructions are in a file Cursor documents.

What is an AGENTS.md file is the shared file. Read it for what belongs in the instructions and what to leave out.
Less verbose coding agents shows a short CLAUDE.md for the shape of the answer, and why “be concise” is too vague to follow.
Use project rules is the course lesson on the same idea.
Draw an architecture diagram of an app your coding agent built puts a snippet in AGENTS.md so later sessions update the map. In Claude Code that snippet is skipped when a CLAUDE.md is already present, unless you import it or read both files.

Rules: Project rules are durable instructions a coding agent loads for a repo. How they work in Cursor, Claude Code, Codex and Grok Build, and when to skip them.
Agent memory: Agent memory is notes a coding agent keeps between sessions. How Claude Code, Codex and Grok Build store them, and what Cursor documents instead.
Context window: The context window is everything a coding agent can see at once. How to check it, free it and keep it small in Claude Code, Codex, Cursor and Grok Build.
Agent skills: An agent skill is a SKILL.md folder that teaches a coding agent one task. Where Claude Code, Codex, Cursor and Grok Build load it, and when to skip one.

All AI glossary entries →

Follow @flaviocopes

Want me to talk about your product? You can sponsor this site.