A Markdown file that Claude Code pulls into context automatically when a session starts, so you do not have to explain your project again each time. Nothing about it is special beyond the filename: no schema, no front matter, no required headings.

Think of it as the standing instructions rather than the documentation. The useful test for any line is whether you would otherwise find yourself typing it into the chat repeatedly — the build command that is not the obvious one, the directory that is generated, the convention a newcomer always gets wrong. Things that are obvious from reading the code do not need to be in it.

You can generate a first draft by running /init in a project, which inspects the repository and writes a starting file. Treat that as a draft: it tends to be longer than it needs to be.

Several places, and they combine rather than replace one another.

• ./CLAUDE.md at the project root. This is the main one. Commit it, so everyone on the team gets the same instructions.
• ./CLAUDE.local.md for personal notes that should not be shared — your own scratch commands, local paths. Add it to .gitignore.
• ~/.claude/CLAUDE.md for preferences that apply to every project you work on.
• Nested files. A CLAUDE.md in a subdirectory is picked up when Claude works with files in that subtree, which suits a monorepo: the root file holds what is true everywhere, and each package documents its own commands.

Claude Code also looks up the directory tree from where you launched it, so a file in a parent folder covering several repositories is picked up too.

An @ followed by a path pulls that file's contents in at the point where the line appears. This keeps one source of truth instead of copies that drift apart.

Paths can be relative to the file, absolute, or start with ~ for your home directory. Imports can chain — an imported file may import another — though only a few levels deep, so do not build a tree out of them. A path inside backticks or a fenced code block is not treated as an import, which means you can write about the syntax without triggering it.

The two everyday uses: importing a shared standards document from several repositories, and importing a personal preferences file from your home directory so it never lands in a commit.

Five categories cover almost every useful line.

• Commands. Build, test, lint, typecheck, and specifically how to run one test rather than the whole suite. This single line saves more time than any other.
• Architecture pointers. Where things live and why, in a handful of lines. Not a tour of the codebase — just the parts that are surprising.
• Conventions. The decisions a formatter cannot enforce: which library to prefer, how errors are handled, naming, whether comments are wanted.
• Verification. What has to be green before a change is finished.
• Never do. Generated directories, files to leave alone, commands with side effects, anything that must not be committed. These are the highest-value lines in the file, because everything not forbidden is treated as allowed.

The whole file goes into context at the start of every session, and it stays there. A long file costs tokens on every single exchange and, worse, dilutes itself: with two hundred lines of guidance, the one rule that actually matters is competing with a hundred and ninety-nine that do not apply today.

A page is a good target. Prefer a pointer to a paragraph — "conventions in docs/style.md" beats reproducing them. Prefer a command to a description of a command. Delete anything you have not needed in a month.

One habit worth forming: when Claude does something you have to correct twice, that is a line for CLAUDE.md. When a line has been in the file for months and nothing has ever depended on it, that is a line to remove.

A realistic file for a Next.js application. Note what is absent: no description of what the product does, no architecture essay, no restating of rules the linter already enforces. Every line is either a command, a pointer, or a boundary.

AGENTS.md is a vendor-neutral convention that a range of coding tools read. CLAUDE.md is Claude Code's own file, with two capabilities the open convention does not define: the @path import syntax, and the layered locations — global, project, local and nested — that merge together.

If you use several tools, do not maintain two files. Put the substance in AGENTS.md, and make CLAUDE.md a single line that imports it. Add Claude-specific notes below that line if you have any; most projects do not.

The reverse also works — keep everything in CLAUDE.md and have AGENTS.md be thin — but it is the worse choice, because AGENTS.md is the file the other tools will find.

Letting it grow. The most common failure by far. A file that started at thirty lines and drifted to three hundred is read less carefully, not more.

Writing aspirations instead of facts. "We use hexagonal architecture" when half the code does not is worse than saying nothing, because it will be applied literally.

Leaving stale commands. If a script is renamed, change the file in the same commit. A command that fails sends the session down a guessing path.

Vague instructions. "Write good tests" has no effect. "Every route handler needs a test for the 400 case" does.

Committing personal preferences. Editor habits and local paths belong in CLAUDE.local.md or your home directory file, not in the shared one.

Forgetting it is a document. It is Markdown, it is read by people as well, and clear headings and lists help both audiences. The Markdown guide covers the syntax, and you can check how it renders in the viewer.