CLAUDE.md: what to put in it, with a free template

What is CLAUDE.md?

CLAUDE.md is a plain text file with instructions for Claude Code. It uses Markdown, a simple way to mark headings and lists. Claude reads it at the start of every session. So you don't have to repeat your build commands, rules and habits in every prompt. There is no set format. Headings and short bullet points work best, as the CLAUDE.md docs explain.

Put it in the top folder of your project. Type /init in Claude Code to make a first version from your code. Then cut it down to what Claude can't work out by itself.

Below you'll find where the file can live, what goes in it, an example, and a free template.

Download CLAUDE.md →Free, no email needed. Plain Markdown: open it in any text editor.

Where Claude Code looks for CLAUDE.md

The CLAUDE.md docs list four places:

Claude Code loads CLAUDE.md from the folder you start in. It also loads one from every folder above it. The files add up; none replaces another. The one closest to where you started is read last. Files in subfolders load later, once Claude works with files in that subfolder.

To see what loaded, type /context in a session. Look under Memory files.

What to put in it

Anthropic's own advice is to keep it short and clear. For each line, ask: would Claude make mistakes without it? If not, cut it. That test is from the best practices.

Put in:

• Commands Claude can't guess: build, test, lint, and the check that proves the work is done.
• Code style rules that differ from the usual ones for your language.
• How you work: branch names, how to commit, what needs your OK.
• Design choices and traps that are special to this project.
• Files and folders Claude must not touch.

Leave out:

• Anything Claude can find by reading the code.
• Common rules it already knows.
• Long tutorials and full API docs (link to them instead), and facts that change often.

Size

Anthropic says to aim for under 200 lines per file. Longer files fill more of Claude's context: the text it holds in mind at once. And Claude follows them less well. That is in the CLAUDE.md docs. Does Claude ignore a rule you wrote? Then the file is probably too long, and the rule gets lost.

Write rules you can check

"Run npm test before committing" works better than "test your changes". "API handlers live in src/api/handlers/" works better than "keep files organised".

An example

# CLAUDE.md

## Commands
- Build: `npm run build`
- Test one file: `npm test -- path/to/file.test.ts`
- Done means: build passes and the tests you touched pass

## Rules
- Propose a plan and wait for my OK before changing more than three files
- After meaningful work, update `project/status.json`: done, next, waiting on me
- Commit only the files you changed, by name

## Don't touch
- `.env` files and anything under `secrets/`
- `dist/` (generated)

That's the whole file. Short is the point.

How I use it

My own CLAUDE.md files are short. Each one says where that project's status lives. Each one has the rule "after meaningful work, update the status file". And each one lists what the agent must not touch. Claude can read everything else from the code.

Imports, local notes and rules

• Imports. A line with @path/to/file pulls another file in, for example @README.md or @AGENTS.md. An imported file can import others, up to four levels deep. Imports keep a long file tidy. But they don't make it lighter: the imported text still loads in every session.
• Comments. Claude Code removes HTML comments that stand on their own lines before Claude sees the file. So you can leave notes for people without using up Claude's context. The template uses this.
• Personal notes. CLAUDE.local.md sits next to CLAUDE.md. It loads after it and stays out of git.
• Rules per folder or file type. For bigger projects, put topic files in .claude/rules/. A rule can be limited to certain paths. Then it only loads when Claude works on those files.

All four are in Anthropic's CLAUDE.md docs.

CLAUDE.md and AGENTS.md

Codex and Cursor read AGENTS.md. Claude Code reads AGENTS.md when the project has no CLAUDE.md. Want one shared file plus a few rules for Claude only? Start your CLAUDE.md with the line @AGENTS.md. The AGENTS.md guide explains the setup and has its own template. The Codex vs Claude Code guide shows how to run both on one project.

About the template

The template is a starting point, not a finished file. Fill in the commands. Delete the sections you don't need. Delete the comments once you've read them (Claude Code removes them anyway). The template is my own work. You are free to use and change it. It holds nothing from my own projects.

Download CLAUDE.md →Free, no email needed. Plain Markdown: open it in any text editor.