Guides

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 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

FileWho it’s forCommit it?
~/.claude/CLAUDE.mdYou, in every projectNo, it’s in your home folder
./CLAUDE.md or ./.claude/CLAUDE.mdEveryone working on the projectYes
./CLAUDE.local.mdYou, in this project: your test URLs, your shortcutsNo, add it to .gitignore
.claude/rules/*.mdThe team, split by topic, or only for some filesYes

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:

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 layoutNothing. 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 releaseA skill: it loads only when it’s needed
Rules for one part of the codebaseA rule in .claude/rules/ with a paths pattern: it loads only when Claude touches matching files
Something that must never happenA 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 commitA hook
Your personal preferencesCLAUDE.local.md or ~/.claude/CLAUDE.md
Passwords, tokens, keysNowhere near it: a project CLAUDE.md is committed (what else leaks this way)
IMPORTANT, ALWAYS, all capsA 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.

Check that Claude reads it, and why it might not follow it

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.mdAuto memory
Who writes itYouClaude
What’s in itInstructions and rulesYour preferences, corrections, decisions
Shared with the teamYes, through gitNo, it’s on your Mac
LoadedEvery session, in fullEvery 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.

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.