MD ReaderWhat is a CLAUDE.md file? What it does and what to put in it
A CLAUDE.md file is a plain text file of standing instructions for Claude Code, Anthropic's coding agent. Claude Code reads it at the start of every session, so you don't have to repeat your test command or project rules each time.
It's written in markdown and doesn't run anything by itself, so opening it to read it is safe. Editing it is different: the agent will act on what you change.
What goes in it
There's no required format. The most useful lines are things the agent can't work out by reading your code:
- Commands: how to build and test, so it can check its own work
- Rules your project follows: for example, where user-facing text must live
- Warnings: a folder not to touch, or a mistake it keeps repeating
A small one looks like this:
# CLAUDE.md
## Commands
- Test: npm test (run this before you finish)
## Rules
- Don't edit files in /generated
- Keep user-facing text in src/i18n
Anthropic's memory documentation suggests staying under 200 lines, because longer files use more of the agent's attention and get followed less reliably.
Where it goes
| File | Used for |
|---|---|
CLAUDE.md in the project's top folder |
Instructions for the project, usually shared through git |
CLAUDE.md in a subfolder |
Instructions read when the agent works in that folder |
~/.claude/CLAUDE.md |
Your personal preferences across all projects |
CLAUDE.local.md |
Your private notes for one project. Keep it out of git |
Files in the folders above where you start Claude Code are also loaded. They're combined rather than replacing each other, so contradictions can confuse the agent.
How to make one
In Claude Code, run /init. It looks through your project and drafts a file with the build commands and conventions it finds. Then add what it couldn't discover.
You don't need one on day one. A good time to start is when you correct the same mistake twice. Add one line, and the next session already knows.
What it can't do
Claude Code treats the file as guidance, not as a hard rule, so it usually follows an instruction but isn't forced to. If something must never happen, Anthropic recommends a hook, which the tool enforces every time. Adding "IMPORTANT" to a line rarely fixes the problem.
Don't put passwords or API keys in it. Project files are usually committed along with the code, so anyone who can see the project can read them.
CLAUDE.md and AGENTS.md
AGENTS.md does a similar job for other tools such as Codex, and Claude Code can also read one that's already in your project. Our guide to the .md files coding agents create explains the others you may see.
Reading it on your phone
Opened in a plain text app, the file shows raw # and ** symbols. To read it formatted on Android:
- Send it to your phone. Claude Code usually runs on a computer, so use Google Drive, an email attachment or a USB cable.
- Tap the file and choose MD Reader, or use Open file in the app.
Headings, tables and code blocks appear formatted, and Contents lets you jump between sections. Tags like <example>, which are common in instruction files, are shown as written instead of disappearing. For Drive, see how to open .md files from Google Drive.
MD Reader doesn't connect to Claude Code or sync with your computer, so what you're reading is a copy. Send it again after it changes. You can tap Edit and change the copy, but Claude Code won't see that until you send the file back to your computer.