CLAUDE.md: what to put in it, where it goes, how long
CLAUDE.md is the briefing Claude Code reads before every session
CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session, so it is where you write down what you would otherwise explain again: build commands, conventions, project layout and the rules Claude keeps getting wrong. Put the team's copy at the root of the repository, keep it under 200 lines, and move procedures into skills, as Anthropic's memory docs recommend.
It is context, not configuration. The same docs say CLAUDE.md content is delivered as a user message after the system prompt, and that Claude reads it and tries to follow it with no guarantee of strict compliance, especially when instructions are vague or contradict each other. That is why anything that must happen every time belongs in a hook rather than in a sentence, and why the way you write the file decides how well it works.
It is also one of the cheapest fixes for a Claude Code bill, because the file rides along in every request; keeping it short is one of the eleven fixes that cut our Claude Code token usage. More guides like this one are in the Claude Code category.
If Claude keeps ignoring instructions your team wrote down, we can go through your setup with you. Book a call with GenovaFlow AI
It can live in four places, and Claude reads all that apply
There are four scopes, and they stack rather than override each other. The memory docs list them from broadest to most specific, which is also the order Claude reads them in.
- The managed policy file is set by IT for everyone on a machine, at
/Library/Application Support/ClaudeCode/CLAUDE.mdon macOS,/etc/claude-code/CLAUDE.mdon Linux and WSL, andC:\Program Files\ClaudeCode\CLAUDE.mdon Windows. - Your user file at
~/.claude/CLAUDE.mdholds your own preferences for every project. - The project file at
./CLAUDE.mdor./.claude/CLAUDE.mdis committed to the repository, so the whole team gets it. - The local file at
./CLAUDE.local.mdholds your private notes for one project, such as a sandbox URL, and goes in.gitignore.
Claude Code loads every CLAUDE.md and CLAUDE.local.md from the folder you start in and from every folder above it, then joins them together, root first, so the instructions closest to where you launched are read last. Files in subfolders below you load later, the first time Claude reads a file in that subfolder. To see what actually loaded, run /context and look under Memory files.
That stacking explains most reports of Claude ignoring a rule. If your user file says one thing and the project file says another, the docs warn that Claude may pick one arbitrarily, so keep personal style in your user file, project facts in the project file, and review both when behaviour drifts.
Put in what Claude cannot work out from the code
Anthropic's best practices give one test for every line: would removing this cause Claude to make mistakes? If not, cut it. What survives is usually the same short list, and the same page has a table of what to include and what to leave out.

The memory docs also say when to add a line: when Claude makes the same mistake a second time, when a code review catches something Claude should have known, when you type the same correction you typed last session, or when a new teammate would need the same context. The last one is the useful test for a business. If you would tell a new contractor on their first morning, tell Claude.
An example for a small automation repository
Here is the shape, written for an example repository of Python scripts and exported n8n workflows. It is an illustration of the format, not a file from a client project.
# Project
Python 3.12 scripts in scripts/, n8n workflow exports in workflows/.
# Commands
- Tests: pytest -q tests/
- Lint: ruff check .
- Run one script without side effects: python -m scripts.<name> --dry-run
# Rules
- Never commit .env or anything in secrets/
- Every script supports --dry-run and logs to logs/<name>.log
- Store dates in UTC; convert only when writing to customers
- IMPORTANT: tests never call the production webhook; use WEBHOOK_URL_TEST
# Gotchas
- workflows/*.json are exports: change the workflow in n8n, then export againEvery line in it is something Claude would otherwise guess wrong or ask about. The IMPORTANT marker sits on one line only, because the best practices point out that if you emphasize many lines, none of them stands out.
Keep it under 200 lines, because longer files are followed less
Anthropic's target is under 200 lines per CLAUDE.md file, and the reason given is adherence as much as cost: longer files consume more context and reduce adherence, per the memory docs. Every line travels with every request in the session, so a bloated file costs tokens all day and buries the rules that matter.
Splitting the file with @path imports does not fix that. Imports keep a long file organized, but the docs are explicit that imported files load together with the CLAUDE.md that imports them, so they cost the same context. Two hard limits sit behind the soft one: a file over 4 MiB is skipped entirely, and a subfolder CLAUDE.md that loads on demand is cut off after 40,000 characters in a 200K context window, with the rest left unread unless Claude opens it.
Claude Code tells you when you are over. A file past the recommended length triggers a warning at startup and in /status, and on Pro, Max, Team and Enterprise plans /usage can name the file in a recommendation such as Trim ~/code/api/CLAUDE.md · 49k tokens per request, according to the costs guide.
Move procedures to skills, file rules to .claude/rules, musts to hooks
Three other places take what does not belong in CLAUDE.md, and each loads only when it is needed. That is how a project with a lot of rules still keeps its main file short.
- A procedure with steps, such as preparing a release or turning call notes into a proposal, becomes a skill: a SKILL.md file whose body loads only when it is used, according to the skills docs.
- A rule for one part of the codebase goes in
.claude/rules/with apathsfield, so it loads only when Claude works with matching files. - Anything that must happen every time, such as running the linter after each edit or blocking writes to a folder, becomes a hook, because hooks run as shell commands at fixed points whatever Claude decides.
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates its input
- Errors use the standard error response formatThat rule file is the example from the memory docs, trimmed. A rule without a paths field loads at launch like the main file, so the saving comes only from scoping it to the files it is about.
Start with /init, then let Claude Code audit the file
You do not have to write the first version. /init analyzes the codebase and writes a starting CLAUDE.md with the build commands, test instructions and conventions it finds; if a file already exists it suggests improvements instead of overwriting it, and it reads Cursor and Copilot rule files if you are moving from those tools, per the memory docs.
From then on, treat the file like code. /doctor proposes cuts for content Claude can derive from the codebase, and /doctor prompt-audit (version 2.1.283 or later) looks for instructions written for older models, references to files that no longer exist, and files that contradict each other, changing nothing until you approve. Notes meant for people can go in HTML comments, which Claude Code strips before the file reaches the model, so they cost no tokens.
If you want this set up across several repositories, or want Claude Code running a real business process rather than ad hoc coding, that is the work behind our custom AI agents. And if you are still deciding whether a coded agent is the right tool at all, n8n vs Zapier vs Make, and where Claude Code fits sets out when it is.
Questions people ask
Should CLAUDE.md be committed to git?
Yes, the project file should be. Anthropic's best practices say to check CLAUDE.md into git so your team can contribute, and the memory docs describe the project file as shared through source control. Private notes for one project go in CLAUDE.local.md, which you add to .gitignore, and preferences for every project go in ~/.claude/CLAUDE.md.
Where is the CLAUDE.md file located?
The team file sits at the root of the repository as ./CLAUDE.md or ./.claude/CLAUDE.md. Your personal file for every project is ~/.claude/CLAUDE.md, your private notes for one project are ./CLAUDE.local.md, and an organization can deploy a managed file to a fixed system path on each machine. Claude Code reads every one that applies, as the memory docs list.
Is CLAUDE.md read automatically?
Yes. Claude Code loads CLAUDE.md files from the folder you start in and every folder above it at the start of each session, and loads files in subfolders the first time Claude reads a file there. Run /context and check Memory files to confirm what loaded. After /compact, the root file is read again from disk, per the memory docs.
What is the difference between CLAUDE.md and AGENTS.md?
They hold the same kind of instructions. AGENTS.md is a plain markdown file that several coding agents read, Cursor among them; CLAUDE.md is Claude Code's own file. Claude Code reads AGENTS.md when no CLAUDE.md exists, and a CLAUDE.md that starts with @AGENTS.md shares one file across tools while adding lines only Claude needs (memory docs).
Should you use CLAUDE.md or a skill?
Use CLAUDE.md for facts Claude needs in every session: commands, conventions, layout and rules that always apply. Use a skill for a procedure with steps, or knowledge that matters only for some tasks, because a skill's body loads only when it is used while CLAUDE.md loads every time. Anthropic's skills docs suggest a skill once a section of CLAUDE.md has grown into a procedure.