The CLAUDE.md file: what to put in it, and what to leave out.

A CLAUDE.md file gives each Claude Code session the same project instructions. Claude Code also maintains auto memory for patterns it learns, but neither system guarantees that every instruction will be followed.

I use a CLAUDE.md in every project. It contains the facts and rules I would otherwise repeat: how to run the project, where important files live, which conventions differ from the obvious choice, and what Claude should not change without asking.

Keep it short. It is context, not enforcement.

Let Claude write the first draft

You do not have to start from a blank file. Run:

/init

Claude reads the project and writes a starting CLAUDE.md from what it finds: build commands, conventions, structure. If the file already exists, /init proposes improvements instead of overwriting it.

Treat the result as a draft. It captures what Claude could work out for itself, which is the part you needed least. The value you add is the next paragraph: the decisions the files do not explain.

Start with the project facts

A small personal website might begin with this:

# Portfolio website

## Project
- Personal site with home, about, projects, and contact pages
- Built with HTML and CSS, without a JavaScript framework

## Design
- Background: #1a1a1a
- Text: #f0f0f0
- Font: Inter
- No rounded corners

## Checks
- Do not delete existing content when editing a page
- Keep images in images/
- Every page needs a title and meta description

That covers the decisions Claude cannot reliably infer from the files. Claude can read the HTML and CSS itself. The file should add what the repository does not explain clearly.

What belongs in it

Add a line when:

• Claude makes the same project-specific mistake again
• a reviewer catches a convention Claude should have known
• you repeat the same correction in another session
• a new team member would need the same fact

I add unusual build commands, folder rules, safety limits, and anything else Claude cannot work out from the repository. Leave out generic advice, copied documentation, and facts Claude can read from standard configuration files.

My rule is simple: if removing a line would not change the work, I remove it.

Long or conflicting instructions consume more context and can reduce adherence. Anthropic currently recommends keeping each file below 200 lines. Mine started at about 10 lines and grew as real corrections appeared. Once it became large, splitting topic-specific guidance was more useful than continuing to add to one file.

Put it in the right place

Shared project instructions can live in either location:

./CLAUDE.md
./.claude/CLAUDE.md

Commit the chosen file when the rules should travel with the repository.

A global CLAUDE.md lives at ~/.claude/CLAUDE.md and applies to every project on that machine. That is the right home for how you want to work in general, and the wrong home for anything specific to one repository. Use CLAUDE.local.md in the project root for private project preferences, and add it to .gitignore.

You can have multiple CLAUDE.md files, and they stack rather than compete: the global one, the project one, and nested files that load when Claude reads code in that part of the tree. Start with a single project file. Add another scope only when you can say what it holds that the one above it should not.

Keep secrets out

Do not put passwords, API keys, tokens, customer data, or private contact details in an instruction file. This includes test passwords.

It is fine to document that local development uses port 3000 or that a named test fixture exists. Point to the approved setup or secret-management process instead of copying a credential.

CLAUDE.local.md keeps personal preferences out of version control. It does not turn secrets into a good idea.

Reuse existing documentation

Use @ imports when the project already has a source of truth:

See @README.md for the project overview.
Use @docs/contributing.md for the Git workflow.

An import loads that content into context, so do not use it as a way to include every document. Link only the files Claude needs in most sessions.

CLAUDE.md and auto memory

Claude Code now has two separate systems:

Both load as context at the start of a session. Auto memory is enabled by default and stored per repository on your machine. You can inspect and edit what it saved.

Use CLAUDE.md for a rule you want the team to see. Do not rely on auto memory for a security requirement or an important project decision.

When the file grows

When the file approaches 200 lines, move topic-specific guidance into .claude/rules/ and multi-step procedures into skills. Path-scoped rules load when Claude works with matching files, while skills load for the relevant task.

If you are not sure what to cut, run /doctor. Its checkup proposes trims for a committed CLAUDE.md, and it aims at the right target: it removes what Claude can read from the codebase anyway, such as folder layouts and dependency lists, and keeps the pitfalls and conventions that differ from the obvious default.

The separate guide explains when I use rule files and how I organise them. The current Claude Code memory documentation explains the complete load order and auto-memory behavior.

Run /memory to browse the instruction and auto-memory locations. Run /context to confirm which instruction files loaded in the current session.

If a second agent works on the same repository

Claude Code is not the only assistant that reads a file at the project root. Codex looks for AGENTS.md, and the obvious move is to write a second set of instructions there.

I would not. Two instruction files describing the same project drift apart, and the day they disagree is the day you stop trusting either.

What I run instead is a short block in AGENTS.md that points at CLAUDE.md and .claude/ as the single source of truth, plus a .agents/skills/ directory whose entries are symlinks back to .claude/skills/. One set of rules, one set of procedures, two agents reading them. When a rule changes it changes once.

The cost is that the pointer file has to stay accurate. Rename a skill and the symlink dangles, which makes it invisible to the second agent rather than loudly broken. That is worth knowing before you build it, not after.

Start with the facts you have already repeated. You can add the next rule when the next real problem appears.

Sources

• How Claude remembers your project, Anthropic. Supports CLAUDE.md scope, load order, imports, auto memory, the 200-line target, and /init, /memory, /context, and /doctor behaviour.
• Extend Claude Code, Anthropic. Explains when instructions belong in CLAUDE.md, path-scoped rules, or reusable skills.
• Custom instructions with AGENTS.md, OpenAI. Confirms that Codex discovers and reads AGENTS.md files from global and project scopes.