CLAUDE.md: what to put in it and what to leave out
CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session. Put in it what you’d otherwise explain again: the commands to build and test, the conventions that differ from the defaults, the traps in your code. Leave out what Claude can read from the code itself, long procedures, and rules that must never be broken: those belong in skills, hooks and deny rules. Keep it under 200 lines. Here’s where it goes, what a good one looks like, and how to check that Claude actually reads it.
- What it is
- Where it goes
- What to put in
- What to leave out
- How long
- Check that it works
- CLAUDE.md vs auto memory
- AGENTS.md and Codex
- Questions
What CLAUDE.md is, and when Claude reads it
Every Claude Code session starts with an empty context. CLAUDE.md is how you carry knowledge from one session to the next without typing it again. Claude Code loads the CLAUDE.md files in the folder you start it in and every folder above it, and puts their text into the conversation right after its own system prompt. A CLAUDE.md in a subfolder loads later, the first time Claude reads or edits a file in that subfolder.
It’s context, not configuration. Claude reads it and tries to follow it, but nothing enforces it. That one fact decides most of what belongs in the file and what doesn’t.
Where it goes
| File | Who it’s for | Commit it? |
|---|---|---|
~/.claude/CLAUDE.md | You, in every project | No, it’s in your home folder |
./CLAUDE.md or ./.claude/CLAUDE.md | Everyone working on the project | Yes |
./CLAUDE.local.md | You, in this project: your test URLs, your shortcuts | No, add it to .gitignore |
.claude/rules/*.md | The team, split by topic, or only for some files | Yes |
All of them add up rather than replace each other. Files from higher folders come first and the one closest to where you started comes last; within a folder, CLAUDE.local.md comes after CLAUDE.md. Organizations can also install a managed CLAUDE.md that applies to everyone on a machine.
To get a first draft, run /init in the project. Claude reads the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests changes instead of overwriting it. Then cut it down: a lot of what /init finds, Claude would find again on its own.
What to put in
Anthropic’s own test for an entry: you’d otherwise explain it again. Claude made the same mistake a second time, a review caught something it should have known, or you typed the same correction you typed last session. In practice that’s four kinds of lines:
- Commands, exactly: how to install, run one test, lint before a commit. “Run
pnpm test” beats “test your changes”. - Conventions that differ from the defaults. If your project does what everyone does, Claude already does it too.
- Traps: generated files, a shared database, the one module that breaks if you touch it.
- When to ask first: new dependencies, infrastructure, anything you want to hear about before it happens.
A whole file can be this short, and short is the point:
CLAUDE.md
# Notes for Claude
## Commands
- Install with `pnpm install`, not npm: the lockfile is pnpm's.
- Run one test: `pnpm vitest run path/to/file.test.ts`
- Before a commit: `pnpm lint && pnpm typecheck`
## Conventions that differ from the defaults
- Dates are stored in UTC. Format them with `lib/time.ts`, never in a component.
- API errors return `{ error: { code, message } }`, never a bare string.
## Traps
- `src/generated/` comes from `pnpm codegen`. Edit the schema, not these files.
- The staging database is shared with the team. Don't run migrations from here.
## Ask first
- Before adding a dependency or changing anything in `infra/`.
Write each line so you could check whether Claude followed it. “Use 2-space indentation” can be checked; “format code properly” can’t.
What to leave out, and where it goes instead
| Instead of writing in CLAUDE.md… | Do this |
|---|---|
| Your architecture and folder layout | Nothing. Claude reads the repository itself. Write down only what isn’t in the code, like why something is the way it is |
| A multi-step procedure, like a release | A skill: it loads only when it’s needed |
| Rules for one part of the codebase | A rule in .claude/rules/ with a paths pattern: it loads only when Claude touches matching files |
| Something that must never happen | A deny rule in your permissions or a hook. CLAUDE.md can be ignored; a hook can’t |
| Something that must happen at a fixed point, like a check before every commit | A hook |
| Your personal preferences | CLAUDE.local.md or ~/.claude/CLAUDE.md |
| Passwords, tokens, keys | Nowhere near it: a project CLAUDE.md is committed (what else leaks this way) |
| IMPORTANT, ALWAYS, all caps | A plain sentence. Current models follow a plain line, and piling on emphasis makes Claude apply the rule where it doesn’t fit |
How long it should be
Under 200 lines per file. Every line is in context from the first message of every session, so a long file costs tokens in every session, and the more there is, the less of it Claude follows. Claude Code warns you at startup and in /status when a file is over the recommended length, and skips one over 4 MiB entirely.
- Imports organize, they don’t save. A line like
@docs/git-workflow.mdpulls that file in, but it loads together with the CLAUDE.md, so the context cost is the same. - Comments are free. HTML comments,
<!-- like this -->, are stripped before Claude sees the file. Use them for notes to your teammates. - Contradictions cost the most. If two lines disagree, across files too, Claude may pick either one.
Check that Claude reads it, and why it might not follow it
/context alllists the files under Memory files. If yours isn’t there, Claude can’t see it. A CLAUDE.md in a subfolder isn’t in that list: it loads later, and a Loaded line with its path appears when it does./memoryopens the files for editing, including the notes Claude saved itself./doctor prompt-auditasks Claude to look for outdated lines, references to files that no longer exist, and instructions that contradict each other. It proposes edits and changes nothing until you say so. It needs Claude Code 2.1.283 or later.- Commit and pull request rules can clash with the ones Claude Code adds itself. If yours aren’t followed, turn the built-in ones off with
includeGitInstructions.
CLAUDE.md vs auto memory
Claude Code has a second memory that it writes itself: notes about your preferences, your corrections and decisions it can’t see in the code, one file per note, with an index called MEMORY.md. They live in ~/.claude/projects/, one folder per repository, shared by all its worktrees, and only on your machine. Claude skips anything your CLAUDE.md already says.
| CLAUDE.md | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What’s in it | Instructions and rules | Your preferences, corrections, decisions |
| Shared with the team | Yes, through git | No, it’s on your Mac |
| Loaded | Every session, in full | Every session, the first 200 lines or 25 KB of the index |
The repository we build Meowdoro in has no CLAUDE.md at all, and my personal one is seven lines about how short the answers should be. The rest sits in auto memory, because it’s the kind of thing Claude only learns from working with me: which session publishes what, which approvals count, what I said yes to last week. For a team repository I’d still write a short CLAUDE.md: auto memory doesn’t leave your Mac.
AGENTS.md, and the same idea in Codex
Codex reads AGENTS.md: a personal one in ~/.codex, then one per folder from the project root down to where you start it, with the closer ones read last. An AGENTS.override.md takes the place of the AGENTS.md next to it. By default Codex stops adding files once they reach 32 KiB together.
Claude Code reads AGENTS.md too, but only when there’s no CLAUDE.md in your folder or above it. To keep one file for both tools, write the instructions in AGENTS.md and put a one-line CLAUDE.md next to it:
CLAUDE.md
@AGENTS.md
Where Meowdoro fits
We built Meowdoro, a focus timer around the MacBook notch for people who work with Claude Code and Codex. Each session gets a ring that shows how full its context is, and your CLAUDE.md is part of what fills it from the very first message. A short file leaves more room for the work. Try it and tell us what’s missing.
Questions
Where should I put CLAUDE.md?
For the team, in the project root as CLAUDE.md or .claude/CLAUDE.md, and commit it. For yourself, in ~/.claude/CLAUDE.md for every project or CLAUDE.local.md for one project, kept out of git.
How long should CLAUDE.md be?
Under 200 lines per file. Longer files cost context in every session and get followed less reliably. Move rules for part of the code into .claude/rules/ with paths, and procedures into skills.
Why is Claude ignoring my CLAUDE.md?
Check /context all to see whether it loaded at all. If it did, the line may be vague, contradicted by another file, or competing with Claude Code’s built-in instructions. For something that must always happen, use a hook instead.
Does Claude Code read AGENTS.md?
Yes, since version 2.1.277, when there’s no CLAUDE.md in your folder or above it. To use both, put @AGENTS.md in your CLAUDE.md.
What’s the difference between CLAUDE.md and memory?
You write CLAUDE.md and share it with your team. Claude writes auto memory itself, from your corrections and preferences, and it stays on your machine. Both load at the start of every session.
Should I run /init?
As a start, yes. Then remove what Claude would find in the code anyway, and add the commands, conventions and traps it can’t.
Related guides
How CLAUDE.md, rules, imports and auto memory work: the Claude Code documentation on memory and best practices, read on November 13, 2026. AGENTS.md in Codex: the OpenAI documentation on AGENTS.md, read on November 13, 2026. The example file is an illustration, not a real project’s.