CLAUDE.md: what to write, where to put it, and how it relates to AGENTS.md

Short answer

CLAUDE.md is a Markdown file that Claude Code reads at the start of every session. Use it for things you would otherwise explain again and again.
For a project, put it at ./CLAUDE.md or ./.claude/CLAUDE.md and commit it. For rules that apply to all your projects, use ~/.claude/CLAUDE.md.
Keep it short (the docs suggest under 200 lines per file): commands Claude can't guess, your conventions, and known pitfalls.
If your repo already has an AGENTS.md and no CLAUDE.md, Claude Code v2.1.277 or later reads the AGENTS.md. If both exist, Claude reads CLAUDE.md only, unless you import @AGENTS.md or change a setting.

Where CLAUDE.md files go

Claude Code reads CLAUDE.md files from several places. They load from the broadest scope to the most specific.

Scope	Location	Use it for	Shared with
Managed policy	Linux/WSL: `/etc/claude-code/CLAUDE.md`, macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`, Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`	Company-wide rules set by IT	Everyone on the machine
User	`~/.claude/CLAUDE.md`	Your personal preferences for all projects	Only you
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Team rules for this repo	Your team, through Git
Local	`./CLAUDE.local.md` (add it to `.gitignore`)	Your own notes for this project, such as a sandbox URL	Only you

How loading works:

Claude Code loads CLAUDE.md and CLAUDE.local.md from the folder you start in and every folder above it.
Files do not override each other. They are all added to the context. Files closer to your working folder are read later.
A CLAUDE.md in a subfolder is not loaded at launch. It loads when Claude reads or edits a file in that subfolder.
To check which files were loaded, run /context and look under Memory files.

For a big project, you can split rules into files under .claude/rules/. A rule file with paths front matter only loads when Claude works on matching files.

What to write

The official guidance is to keep facts Claude needs in every session: build and test commands, conventions, project layout, and "always do X" rules. Good things to include:

Bash commands Claude can't guess
Code style rules that differ from the defaults
How to run tests, and which test runner you prefer
Branch naming and pull request rules
Architecture decisions that are specific to your project
Environment quirks, such as required environment variables
Gotchas that are not obvious from the code

Write rules that can be checked. "Use 2-space indentation" works better than "format code properly". Group rules under headings and bullets.

A small example:

# Commands
- Build: `npm run build`
- Test one file: `npm test -- path/to/file.test.ts`

# Code style
- Use ES modules (import/export), not CommonJS (require)
- API handlers live in `src/api/handlers/`

# Workflow
- Run `npm test` before committing
- Branch names: `feature/<short-name>`

You can pull in other files with @path/to/file, for example a line like this in CLAUDE.md:

See @README for an overview.

Write the @ reference as plain text: an @path inside backticks is not imported. Relative paths resolve from the file that contains the import, and imports can nest up to four levels deep. Imported files also load at launch, so imports help you organize but do not save context.

To get a first draft, run /init. Claude looks at your codebase and writes a starting CLAUDE.md. If one already exists, /init suggests improvements instead of overwriting it.

What not to write

Long documents. Longer files use more context and Claude follows them less reliably. Link to detailed API docs instead of pasting them.
Things Claude can learn from the code, such as file-by-file descriptions or standard language rules.
Information that changes often.
Vague advice like "write clean code".
Multi-step procedures or rules for one part of the code. Move these to a skill or a path-scoped rule.
Secrets (our advice). A project CLAUDE.md is shared through version control, so anyone who can read the repo can read it. Write the name of the environment variable or where the secret is stored, never the value.

A useful test for each line: "Would removing this cause Claude to make mistakes?" If not, cut it. Also remember that CLAUDE.md is guidance, not enforcement. If something must happen every time, use a hook.

How CLAUDE.md relates to AGENTS.md

AGENTS.md is an instruction file used by other coding agents. According to the Claude Code docs (reading it directly needs v2.1.277 or later):

Your repo has	Claude reads
`AGENTS.md` and no CLAUDE.md or CLAUDE.local.md in your folder or above	`AGENTS.md`
`AGENTS.md` and a CLAUDE.md or CLAUDE.local.md	CLAUDE.md files only
A CLAUDE.md that imports `@AGENTS.md`	CLAUDE.md, with AGENTS.md included

Your ~/.claude/CLAUDE.md does not count for this check. A CLAUDE.local.md does count, so adding one stops Claude from reading your AGENTS.md (with the default setting).

To keep one shared file for all tools, put this in a CLAUDE.md next to it and add Claude-only notes below:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

You can also change which files load: run /config and set Project instructions (for example claude-md-and-agents-md to read both).

Editing CLAUDE.md later

Run /memory in a session. It lists your CLAUDE.md, CLAUDE.local.md, and other memory files across user and project scopes. The user and project CLAUDE.md appear even if they don't exist yet. Pick one to open it in your editor; picking a missing file creates it.
To edit your global file, choose the user entry in /memory, or open ~/.claude/CLAUDE.md directly.
You can ask Claude, for example "add this to CLAUDE.md".
Run /doctor prompt-audit (Claude Code v2.1.283 or later) to find outdated or conflicting instructions. Nothing changes until you ask Claude to apply the fixes.
Treat it like code: review it when things go wrong and prune it regularly.
On your phone, you can open the file on github.com, tap the pencil icon to edit it, and commit the change.

Fix it from any browser with PlainHub

A project CLAUDE.md is just a Markdown file in your Git repository, so you don't need your laptop to fix a rule. PlainHub is a browser editor for Markdown files in your own GitHub repositories. It works on phone browsers, every save is a Git commit so the history is kept, and your files go between GitHub and your browser without PlainHub storing them. If you use Claude Code, the plainhub npm package includes an MCP server (claude mcp add plainhub -- plainhub-mcp) that lets Claude open a file in the PlainHub editor.

Try PlainHub without signing in

FAQ

Should I use ./CLAUDE.md or ./.claude/CLAUDE.md?
Either works for project instructions. Pick one and commit it.

Is CLAUDE.local.md still supported?
Yes. The current docs list ./CLAUDE.local.md for personal project notes. Add it to .gitignore. It loads after CLAUDE.md in the same folder.

Claude is ignoring my CLAUDE.md. What should I check?
Run /context to confirm the file loaded. Make the rule more specific, remove rules that conflict, and shorten the file. A CLAUDE.md in a subfolder only loads when Claude works in that subfolder.

Sources

Checked: 2026-10-20