Progress will not be saved. This browser is blocking storage (often private browsing). You can still learn, but closing the tab loses your progress.
Practice needs JavaScript. The reading works without it.Back to the reading
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.
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.
Many people write CLAUDE.md like a project introduction. Most of that is filler:
- Folder trees, dependency lists, architecture overviews. Claude reads
package.jsonand opens the folders. The/doctorcommand 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.
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 testbefore 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.
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:
/initgenerates a starting version from your codebase. From there your work is mostly deleting. The next lesson covers/initin detail./doctorsuggests cutting what Claude can work out from the code./doctor prompt-auditfinds 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.
If Claude seems to ignore a line, check in this order:
- Did the file load? Type
/context alland look at the list under Memory files. If the file isn't there, Claude can't see it. - Is the line concrete enough? Rewrite it so it can be checked.
- Does another line contradict it? Look through the project's other
CLAUDE.mdfiles. - 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.