CLAUDE.md: What It Is and What to Put in It

Short answer: CLAUDE.md is a Markdown file that Claude Code reads at the start of every session in that folder. Put in it what you’d otherwise repeat in every chat: what the project is, the commands to install, run and test it, the rules for how Claude should work, and the limits it must not cross. Keep it short and specific. Leave out anything Claude can read from the code itself.

This guide covers where the file goes, what belongs in it, and a starter you can copy.

What is a CLAUDE.md file?

Claude Code is Claude in your terminal: it reads your project, edits files and runs commands with your permission. Every session starts with no memory of the last one. CLAUDE.md is how you give it the same context every time without typing it.

Claude Code loads the file automatically, so the rules in it apply from the first message. Think of it as the onboarding note you’d write for a new developer on day one, short enough that they’d actually read it.

If you haven’t set up Claude Code yet, How to Install Claude Code walks through it on Mac, Windows and Linux.

Where does CLAUDE.md go?

Location	Applies to	Use it for
`CLAUDE.md` in the project root	Everyone working in that repo	Project rules, commands, stack
A `CLAUDE.md` in a subfolder	Work inside that folder	Rules for one part of a monorepo
`~/.claude/CLAUDE.md` in your home folder	Every project on your machine	Your personal habits and preferences

Commit the project file to git, so the whole team shares the same rules. Keep personal preferences in your home folder, so they don’t land in everyone’s repo.

What should you put in CLAUDE.md?

The sections that pay off most:

What the project is. One or two sentences: who uses it and what matters most (speed, correctness, money, privacy).
Commands. Install, run, test, test one file, lint, build. Exact commands, not descriptions.
How to work. When to show a plan first, how big a change may be, when to ask instead of guessing.
Code style that isn’t obvious from the code. Naming rules, where new files go, patterns to avoid.
Testing rules. Which tests to write, and that they must pass before Claude says it’s done.
Git and safety limits. Never push, never touch .env, never run destructive database commands without asking.
A finish line. The checks Claude runs before it reports a task complete.

What should you leave out?

Anything the code already says. Claude reads your files. Describing every folder wastes the space.
Long documentation. Link to docs/ instead and say when to read which file.
Secrets. No keys, passwords or tokens, ever.
Vague wishes. “Write clean code” changes nothing. “Functions over 40 lines get split” does.
Rules you don’t enforce. If you’d accept the change anyway, the rule is noise.

A useful test: if you deleted a line, would Claude do something wrong? If not, delete it.

What does a good CLAUDE.md look like?

A short example for a web app:

# Invoices

Invoicing app for small agencies. Correctness of amounts matters more than speed.

## Commands
- Install: `npm install`
- Run: `npm run dev` (http://localhost:3000)
- Tests: `npm test` · one file: `npx vitest run path/to/file.test.ts`
- Lint: `npm run lint`

## How to work with me
- Before changing more than 3 files, a schema or a dependency: show the plan and wait.
- Amounts are integers in cents. Never use floats for money.
- Ask one precise question when something is unclear.

## Limits
- Never push, force-push or edit .env files.
- Never run migrations against anything but the local database.

## Done means
- `npm test` and `npm run lint` pass, and you've listed what you changed.

That is about 20 lines, and every one of them changes what Claude does.

How do you keep CLAUDE.md up to date?

Add a rule when Claude repeats a mistake. If you correct the same thing twice, it belongs in the file.
Ask Claude to update it. At the end of a session: “Add what we learned today to CLAUDE.md, in one line each.”
Review it like code. A pull request that changes the build should change the commands in CLAUDE.md too.
Prune it. Every few weeks, delete rules that no longer apply.

How is CLAUDE.md different from a Claude skill?

CLAUDE.md is always loaded, for one project. A skill is a method Claude loads only when a request matches it, in any project. Put project facts in CLAUDE.md and reusable procedures (write a changelog, review a pull request, humanize a draft) in skills. What Are Claude Skills? explains how they load, and How to Create a Claude Skill shows how to write one.

FAQ

Is CLAUDE.md required?

No. Claude Code works without it. The file saves you from repeating the same context in every session.

How long should CLAUDE.md be?

As short as it can be while still changing what Claude does. Many good files are 20 to 80 lines.

Can Claude write my CLAUDE.md?

Yes. Run /init in Claude Code and it drafts one from your project. Then cut what’s obvious and add the rules only you know.

Does CLAUDE.md work in Claude.ai?

No, it’s read by Claude Code. On Claude.ai, project instructions do a similar job.

Should CLAUDE.md be committed to git?

The project file, yes, so everyone shares it. Keep personal preferences in ~/.claude/CLAUDE.md.

Start from a complete file instead of a blank one. The CLAUDE.md Starter in the Nexin library covers house rules, stack and commands, unit testing rules, git and safety limits, and a finish line Claude checks before it says done. Fill in the brackets once. It comes with Nexin Lite ($14 once, 7-day money-back guarantee) or Nexin Pro ($19 a month, 7 days free). Either plan opens the whole library. See pricing.