Lesson 2.115 min · 5 cards · 8 exercises · 1 mission

CLAUDE.md: what goes in, what stays out

Write down what Claude can't see for itself, make it concrete enough to follow, and keep the file short.

Last week you fixed the double-delete bug in todo-api. Today you open a new session to add an endpoint that restores deleted todos, and you find yourself telling Claude exactly what you told it last week: which command runs the tests, that deletes here are soft, that find also returns deleted rows. Every Claude Code session starts blank, so unless it's written down somewhere, you repeat it every time. The place to write it down is CLAUDE.md.

What CLAUDE.md is

CLAUDE.md is an ordinary Markdown file, usually at the root of the project. Claude Code reads it at the start of every session, so whatever is in it is always part of Claude's context without you saying it. The file is committed with the code, so the whole team shares it.

Two things are worth getting right from the start.

First, CLAUDE.md is context, not enforced configuration. Claude reads it and tries to follow it, and usually does, but nothing guarantees it. If something must never happen, such as writing into a folder of generated code, that is a job for a hook, which you'll meet in level 6.

Second, every line in the file takes a little of Claude's attention on every task, relevant or not. The more filler the file holds, the easier it is for the important lines to get lost.

What to write

A simple test: only write down what Claude can't find by reading the code, or what it would have to dig up again every session. According to the docs, the lines that earn their place usually fall into four groups:

  • How to check work in this repo: the exact test, typecheck and lint commands, and how to run a single test file. With the commands, Claude can check its own work.
  • Places where the code misleads: an old pattern that's everywhere but that new code must not copy, or a folder that looks unused but isn't.
  • Decisions that aren't in the repo: which error helper the team settled on, how deploys work, what needs a migration review.
  • Anything you've had to correct twice.

The docs also suggest when to add a line: Claude makes the same mistake a second time; a review catches something Claude should have known; you notice yourself typing the same correction as last session; or a new teammate would need the same context.

For todo-api, a file that does the job can be this short:

# Commands
- Install: `npm install`
- Test: `npm test`
- One file: `node --test test/todos.test.js`

# Gotchas
- Deletes are soft: set `deletedAt`, never remove rows
- `db.todos.find` also returns soft-deleted rows; check `deletedAt`

The last line is exactly what caused last week's bug. Write it here and Claude won't trip over it again.

What to leave out

Many people write CLAUDE.md like a project introduction. Most of that is filler:

  • Folder trees, dependency lists, architecture overviews. Claude reads package.json and opens the folders. The /doctor command even suggests cutting exactly these parts.
  • Vague lines that can't be checked, such as "write clean code".
  • Multi-step procedures, such as release steps. They belong in a skill (level 3): Claude only reads a whole skill when a task needs it, so it doesn't take space in every session.
  • Rules that only apply to one part of the code, such as rules just for src/routes/. Those belong in a path-scoped rule (lesson 2.3), loaded only when Claude works on matching files.
  • Rules with no exceptions. In CLAUDE.md, Claude follows them nearly every time. For every time, use a hook.

Writing so Claude follows it

Because Claude treats CLAUDE.md as context, how you write decides how reliably it's followed. The docs give some easy-to-remember pairs:

  • "Use 2-space indentation" instead of "Format code properly".
  • "Run npm test before committing" instead of "Test your changes".
  • "API handlers live in src/api/handlers/" instead of "Keep files organized".

The first of each pair can be checked; the second can't.

Two more habits. Organise with headings and bullets: clear sections are easier to follow than dense paragraphs. And stay consistent: if two lines contradict each other, Claude may pick either one arbitrarily.

A small tip: block HTML comments such as <!-- notes for maintainers --> are stripped before the content reaches Claude. You can leave notes for colleagues without spending context on them.

Keeping the file short

The docs recommend keeping each CLAUDE.md under 200 lines. Longer files cost more context and are followed less reliably. When a file goes over the recommended length, Claude Code warns you at startup and in /status.

Three tools help keep it short:

  • /init generates a starting version from your codebase. From there your work is mostly deleting. The next lesson covers /init in detail.
  • /doctor suggests cutting what Claude can work out from the code.
  • /doctor prompt-audit finds instructions written for older models, references to files or commands that no longer exist, and lines that contradict each other. It only reports; your files don't change until you ask it to apply the edits.

When Claude doesn't follow it

If Claude seems to ignore a line, check in this order:

  1. Did the file load? Type /context all and look at the list under Memory files. If the file isn't there, Claude can't see it.
  2. Is the line concrete enough? Rewrite it so it can be checked.
  3. Does another line contradict it? Look through the project's other CLAUDE.md files.
  4. Is the file too long? The important line may be getting lost.

Don't reach for IMPORTANT in capitals. The docs say plainly that it rarely fixes anything: either the file has grown too long, or the line is a no-exceptions rule that belongs in a hook. In the same way, a line saying "always typecheck before you finish" tells Claude the command so it can check itself; to require a passing typecheck, you need a Stop hook.

Next lesson: there isn't just one CLAUDE.md. There are four levels, from the whole company down to just you, plus the memory Claude writes for itself.

Practice lesson 2.1

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.