CLAUDE.md: how to write it so Claude Code actually follows it

A CLAUDE.md is a Markdown file that Claude Code reads at the start of every session and puts into its context: it holds the commands, conventions and gotchas it can’t figure out by looking at the code. For Claude to follow it, it has to be short, with instructions that can be checked: the official documentation recommends fewer than 200 lines per file. Below you’ll find how Claude Code loads it (checked against the documentation today), what to include and what not to, the layered system we use every day, and two templates to copy.

If you don’t use Claude Code yet, start with the Claude Code guide and come back here.

How Claude Code loads CLAUDE.md files#

Claude Code doesn’t read just one CLAUDE.md: it looks for several and adds them together; they don’t override each other. These are the locations, in the order they enter the context, according to the official documentation as of October 16, 2026:

The part people most often miss is how it works with folders:

1. Upward, at startup. It loads the CLAUDE.md (and CLAUDE.local.md) from the folder where you open Claude Code and from every parent folder. They go from the root down, so whatever is closest to your folder is read last.
2. Downward, on demand. CLAUDE.md files in subfolders aren’t loaded at startup: they come in the first time Claude reads, writes or edits a file in that subfolder.
3. Imports with @path. Inside a CLAUDE.md you can write @README or @docs/git.md and that file gets expanded into the context. Relative paths are resolved from the importing file, it supports up to four levels of chained imports, and if the file is outside your project, it asks you to approve it the first time.
4. Rules in .claude/rules/. They still exist: .md files by topic. Without a header they’re always loaded; with a paths field in the frontmatter they only come in when Claude touches files that match the pattern.

Two details change how you write it. First: the contents of CLAUDE.md reach the model as a user message after the system prompt, not as part of the system prompt. It’s context, not mandatory configuration; if something must always happen, it belongs in a hook. Second: HTML block comments (<!-- note -->) are stripped before being passed to the model, so you can leave notes for humans without spending context.

To see what has actually loaded, type /context in the session and look at the Memory files list. /memory lists your memory files, lets you open them in your editor, and turns auto memory on or off.

AGENTS.md: when it’s read and when it isn’t#

According to the official documentation, since version 2.1.277 Claude Code reads AGENTS.md, the file other coding agents use. But by default only if there’s no CLAUDE.md or CLAUDE.local.md in your folder or any parent folder. If both exist, it reads only the CLAUDE.md files. You can change this in /config, under Project instructions.

This hits us directly: since we have a CLAUDE.md in the root folder of all our projects, a standalone AGENTS.md inside a project isn’t read with the default settings. The fix the documentation recommends, and the one we use in a Next.js project, is to import it from the CLAUDE.md:

@AGENTS.md

# my-project
...

On Windows, use the import rather than a symbolic link: the documentation itself warns that creating them requires administrator rights or developer mode, and git may check them out as a one-line text file.

Less is more: every line competes for attention#

Everything you put in CLAUDE.md goes into every request in the session. The official documentation is blunt about it: aim for fewer than 200 lines per file, because longer files “consume more context and reduce adherence.” And in the best practices guide it proposes a test for every line:

«Would removing this cause Claude to make mistakes?» If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!

In other words: if removing the line wouldn’t make Claude get something wrong, it doesn’t belong. Three practical consequences:

• Splitting into imports saves nothing. Imported files are also loaded at startup. It tidies things up, but it doesn’t slim anything down.
• Anything that only matters in one part of the code goes into a rule with paths or a skill, which load only when needed.
• “IMPORTANT” wears out. The documentation recommends adding emphasis to the line Claude keeps skipping, and only that one: if you put it on many, none stands out.

It also warns about contradictions: if two instructions clash (for example, one in the global CLAUDE.md and one in the project’s), Claude may pick one arbitrarily.

What to put in and what to leave out#

Secrets deserve a separate note. The project CLAUDE.md usually goes into git, and even if it doesn’t, the model reads it every session. In our files the pattern is to say where it is, never what it is: one of them says an admin password is “ONLY in a file in .secretos/ (ignored by git).” You’ll see the general rule in the global template below.

What changes every day (what was left half-done, what’s up tomorrow) doesn’t go there either. We keep that in a per-project status note in the assistant’s memory, which it receives with every task. That way the CLAUDE.md says how the work is done and the note says where we are.

All of the above fits into four questions. It’s the filter we run every line through before keeping it:

Desliza para ver la figura completa

Our layered CLAUDE.md system#

At GamzyHost we work with our own assistant built on Claude Code on a Windows Server 2022 VPS, which works in more than twenty projects every day (we describe it in how to build your own AI assistant). Each project lives in C:\Proyectos\<Área>\<proyecto> and every folder level has its own CLAUDE.md. Since Claude Code loads every parent folder, when a project is opened the model receives all three layers combined, plus the fourth if it touches the part that has one.

Desliza para ver la figura completa

We use a parent folder (C:\Proyectos) instead of ~/.claude/CLAUDE.md for the common rules for a practical reason: that way they only apply to the projects, not to any session opened on the machine, and they travel with the folder if we move it. These are real excerpts, trimmed and adapted.

Common layer (23 lines in total). What applies to any project: where everything goes, where finished work gets logged, and what isn’t touched without permission.

# Ferran's projects: rules for any Claude Code session

## Organization
- One parent folder per project with everything for the project inside,
  each part in its own subfolder (web, panel, documents, screenshots...).
- Work only inside the project folder.

## Caution
- Dependencies (node_modules, .venv...) are not copied:
  install them with the project's package manager before running anything.
- No git push, deployments or server changes without his OK.
- Never write secrets (keys, tokens, passwords) in project files
  or in notes.

Area layer (5 lines). Almost nothing: what the area is and which projects it has. That’s all it needs.

# Otros area
Projects that don't have their own area yet. If one grows or fits
into another area, it moves there.
Projects: `proyecto-a`, `proyecto-b`, `blog-ia`, ...

Project layer (about 40 lines in the one for a Node app). This is where the real mistake-savers are: exact commands, how to verify, how to deploy, and the gotchas.

## How we work (app/)
- Stack: Node 22 + Express 5 + better-sqlite3 in `server/`;
  React 19 + Vite + Tailwind v4 in `src/`; `shared/` is used by both.
- Commands: `npm install`; `npm run build:app`; `npm test` (vitest);
  `npx tsc --noEmit -p tsconfig.json`.
- E2E: it marks states on the account it logs in with. Do NOT run it with
  Ferran's real account; create a test account first.
- Migrations in `server/db.ts`: never edit a published one, add a new one.

The best lines in our CLAUDE.md files are gotchas that cost us an afternoon: in an Expo project, that npx expo start --web fails with web.output: "static" and for screenshots you have to switch it to "single" without committing; in a video project, that the ffmpeg bundled with Remotion is stripped down and you have to measure loudness with loudnorm. None of them can be inferred from the code.

CLAUDE.md template for a Node web project#

Copy it into the project root and fill in only what applies. If a section ends up empty, delete it.

# project-name

What it is in one sentence and who it's for. Where it runs (production, staging).

## How we work
- Stack: Node 22 + Express 5 in `server/`; React 19 + Vite in `src/`.
- Install: `npm install` (node_modules is not in the repo).
- Development: `npm run dev` (port 3000). Build: `npm run build`.
- Before calling something done: `npm test` and `npx tsc --noEmit`.
- Variables: see `.env.example`. The real `.env` is never shown or copied.

## Conventions
- ES modules (`import`), not `require`.
- Migrations in `server/migrations/`: never edit a published one; add a new one.
- UI text in Spanish.

## Deploying
- `npm run deploy`, only with sign-off from <owner>.
- Never `git push --force` or direct commits to `main`.

## Gotchas
- (Empty at first: add here anything Claude gets wrong twice.)

Template for the global layer#

It can go in ~/.claude/CLAUDE.md (all your sessions) or in a parent folder containing your projects, as we do. It should be the shortest of all, because it goes into everything.

# Rules for any project

## Organization
- Everything for a project goes inside its folder. Nothing loose outside it.
- Temporary files go in the project's `temp/`; delete them when done.

## Caution
- No git push, deployments or server changes without my confirmation.
- Never write secrets in files or notes: say where they are, not what they are.
- Dependencies are not installed: install them before running anything.

## When you finish
- Say what you changed and how you verified it.
- If you learn something technical worth knowing next time, add it
  to the project's CLAUDE.md, in one line.

The last line is what keeps the system alive: the agent itself records the gotchas it discovers, and you just check that they’re short.

Getting started with /init and keeping it alive#

For a project without a CLAUDE.md, the quick route is /init: Claude analyzes the code and generates one with the build commands, tests and conventions it finds. If one already exists, it suggests improvements instead of overwriting it. According to the documentation, with the CLAUDE_CODE_NEW_INIT=1 variable, /init becomes a multi-phase wizard that asks what you want to set up (CLAUDE.md, skills, hooks) and shows you a proposal before writing anything.

What /init generates is a draft. Cross out what Claude would infer on its own (the folder tree, the dependency list) and keep what it wouldn’t.

After that, the rule for adding a line is the one the official documentation proposes: when Claude gets the same thing wrong twice. Once can be chance; twice means it’s missing information. Other signs a line is due:

• You type the same correction in the chat as in the previous session.
• A code review finds something Claude should have known.
• Someone new to the project would need that same piece of information.

To add it, just say so: “add this to CLAUDE.md.” If you only say “remember that…”, it saves it to its auto memory, which is something else (more on that in a moment). And for cleanup, the documentation describes /doctor prompt-audit (since version 2.1.283), which reviews your instruction files for stale rules, references to files that no longer exist and contradictions, and doesn’t change anything until you ask it to.

CLAUDE.md, rules, skills and memory: what goes where#

The boundary with skills is the one people confuse most. If it’s a multi-step procedure (deploying, publishing, preparing a report), it goes in a skill: it only loads when needed. In CLAUDE.md, at most, one line saying that skill exists. The documentation sums it up the same way: if an entry is a procedure or only affects one part of the code, move it into a skill or a rule.

Auto memory stores notes that Claude writes on its own in ~/.claude/projects/<proyecto>/memory/, and you can turn it off with /memory or with the CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 variable. We keep it off in our assistant’s sessions: by our measurements, its instructions added about 3,000 tokens to every message, and our memory already lives in an Obsidian vault organized by project. If you don’t have anything similar, leave it on: it’s useful for what you don’t want to write by hand.

Common CLAUDE.md mistakes#

• Pasting the README. Whatever is already in the code or the project’s documentation, Claude reads if it needs it. CLAUDE.md is for what isn’t written anywhere else.
• Instructions that can’t be checked. “Write clean code” changes nothing. “Run npm test before committing” does. The documentation gives the example of “use 2-space indentation” versus “format code properly.”
• Contradictions between layers. If the global layer says one thing and the project layer another, Claude may follow either. Review the layers together every so often.
• Using it as a lock. A “don’t edit .env” line is a request, not a guarantee. What must always hold goes in a hook or in permissions.
• Putting in today’s status. Tasks, what was left half-done, the date of the last session: it goes stale in hours and then confuses things. That goes in a separate note.
• Assuming it’s loaded. A CLAUDE.md in a subfolder doesn’t show up in /context at startup, and an AGENTS.md with a CLAUDE.md above it isn’t read by default. Check before blaming the model.
• Splitting it into imports to “slim it down.” It tidies things up, but the context cost is the same.

What to do now#

1. Open Claude Code in your project and run /context: see which CLAUDE.md files it’s loading today.
2. If you don’t have one, run /init and trim the draft with the “would it get this wrong without this line?” test.
3. Copy the global template and keep only the rules you actually apply across all your projects.
4. Leave the “Gotchas” section empty and fill it with every mistake Claude repeats twice.

If you want the agent to know how to carry out complete tasks, continue with Claude skills. If you want to connect it to your services, see what MCP is.