CLAUDE.md best practices from Anthropic's docs, checked 26 Oct 2026: what to put in it, where each file lives, the 200 line target and how AGENTS.md loads.
The best CLAUDE.md is short, concrete and checked often: under 200 lines, only what Claude needs in every session, and hooks for anything that must never be skipped. These eight rules come from Anthropic’s memory docs and best practices page, read on 26 Oct 2026.
Running several Claude Code agents? Munder Difflin is free and open source: a desktop app that runs a team of AI agents for all kinds of knowledge work, coding included, on your own computer. The install guide covers setup. For habits beyond this file, see Claude Code best practices.
What is a CLAUDE.md file? # #
A plain markdown file of instructions that Claude Code loads at the start of every session. The memory docs say each session “begins with a fresh context window”, and CLAUDE.md is how your build commands, conventions and rules carry over. Claude writes a second kind of memory itself, auto memory, from your corrections.
One line matters more than the rest: Claude treats CLAUDE.md “as context, not enforced configuration”. It is advice Claude reads, not a lock.
Where should CLAUDE.md files live? # #
Four places, loaded from broadest to most specific, per the memory docs on 26 Oct 2026:
| Scope | Where | Shared with |
|---|---|---|
| Managed policy | /Library/Application Support/ClaudeCode/CLAUDE.md on macOS |
Everyone in the organisation |
| User | ~/.claude/CLAUDE.md |
Only you, every project |
| Project | ./CLAUDE.md or./.claude/CLAUDE.md |
Your team, through git |
| Local | ./CLAUDE.local.md , added to.gitignore |
Only you, this project |
Files above your working folder load at launch, and files in subfolders load when Claude touches a file there. They add up rather than replace each other, so the line closest to where you started Claude is read last.
What should go in CLAUDE.md? # #
Facts Claude should hold in every session and cannot work out from the code. The memory docs name build commands, conventions, project layout and “always do X” rules, and say to add a line when:
- Claude makes the same mistake a second time.
- A code review catches something Claude should have known.
- You type the same correction you typed last session.
- A new teammate would need the same context.
Write lines you could check. The docs give examples: “Use 2-space indentation” instead of “Format code properly”, and “Run npm test before committing” instead of “Test your changes”. Here is a short project file in that style:
- Run `npm run build` before you say a task is done.
- Run `npm test -- path/to/file` for one test file, not the whole suite.
- TypeScript strict mode; no `any`.
- API handlers live in `src/api/handlers/`.
- Never edit files in `generated/`.
A procedure with many steps, or a rule for one corner of the repo, belongs in a skill or a path scoped rule.
How long should CLAUDE.md be? # #
Under 200 lines per file. The docs say longer files “consume more context and reduce adherence”. Three tools keep it short:
- Path scoped rules. Files in
.claude/rules/with apathsfield load only when Claude works on matching files. - Imports.
@path/to/filepulls in another file, up to four hops deep. This organises a long file but does not cut its context cost. - HTML comments. Block comments are stripped before Claude sees the file, so notes for people cost no tokens.
The best practices page asks of every line: “Would removing this cause Claude to make mistakes?” If not, cut it.
Does Claude Code read AGENTS.md? # #
Yes, from v2.1.277, but not next to a CLAUDE.md by default. The memory docs say Claude reads AGENTS.md when you have no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working folder or above it. Add any one of those and AGENTS.md stops .
To keep one file for every agent, import AGENTS.md from CLAUDE.md, or set Project instructions in /config to claude-md-and-agents-md so Claude reads both. Codex, OpenCode and Pi all read AGENTS.md, so one shared file keeps a mixed team in step.
How do you keep CLAUDE.md up to date? # #
Treat it like code. The best practices page says to check it into git and review it when things go wrong. Run /init for a starter file, /context to confirm it loaded and /memory to list and open your memory files. From v2.1.283, /doctor prompt-audit looks for stale instructions, missing files and contradictions, and changes nothing until you say so.
If one rule keeps slipping, the page suggests adding “IMPORTANT” to that line alone. If a rule must hold every time, the memory docs point to a PreToolUse hook instead; see Claude Code hooks explained.
CLAUDE.md best practices at a glance, checked 26 Oct 2026 # #
| Rule | From |
|---|---|
| Under 200 lines per file | Memory docs |
| Only what applies in every session | Best practices page |
| Concrete lines you could verify | Memory docs |
| Path scoped rules and skills for the rest | Memory docs |
| No two lines that disagree | Memory docs |
Commit the project file, keep CLAUDE.local.md private |
Both pages |
| Emphasis on the one line that slips, not many | Best practices page |
| Hooks for rules with no exceptions | Both pages |
FAQ #
How long should a CLAUDE.md file be?
Under 200 lines per file. Anthropic's memory docs say longer files use more context and reduce adherence, and that imports help you organise a long file but do not cut its context cost. Checked 26 Oct 2026.
Does Claude Code read AGENTS.md?
Yes, from Claude Code v2.1.277. By default it reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. The Project instructions setting in /config can make it read both.
Should CLAUDE.md be committed to git?
The project CLAUDE.md, yes: Anthropic's best practices page says to check it into git so your team can contribute. Keep personal notes in CLAUDE.local.md and add that file to .gitignore.
Why does Claude ignore my CLAUDE.md?
Usually the file is too long or two lines disagree. Anthropic's docs say a rule gets lost in a long file and that Claude may pick one of two conflicting instructions arbitrarily. For a rule with no exceptions, use a hook.