CLAUDE.md

CLAUDE.md is a Markdown file in your project that Claude Code loads at the start of every session, so its rules and facts are in place before you type anything.

Last updated: 29 Sep, 2026 · Claude Code

Every session starts with an empty conversation, and this file is what stops you explaining the same things every morning.

In the video the first question made Claude Code scan every file, because it had no context about the project. So the video asks what CLAUDE.md is for, and Claude answers: a special instruction file that Claude Code loads into context at the start of every conversation in a project, where you put guidance you want followed without repeating it each session.

The file for this course's project is below, kept short because every session reads it.

One for this project

# Link shortener

Codes are generated in `shorten.py`. Storage is in-memory in `store.py`.

## Rules
- Never edit `store.py` without being asked; other code depends on its exact shape.
- When you describe a function, always name the file it is in.

Two facts and two rules. Nothing about Python, nothing about good code in general, nothing it could work out by reading the files. Only what somebody joining the project would have to be told.

Proof that it is loaded

The second rule is deliberately easy to check: always name the file a function lives in. The same question is asked twice below, once with the file present and once with it moved out of the way.

claude -p "How are short codes generated?"

`next_code()` in shorten.py:

1. Get count from store (how many URLs shortened)
2. First character: `n % 26` -> cycles a-z (mod operation)
3. Second part: `n // 26` -> integer division, increments after every 26 codes

mv CLAUDE.md /tmp/ && claude -p "How are short codes generated?"

Short codes generated by counting total links shortened, then mapping to
letter+number format:

```python
n = store.count()  # Total links shortened so far
ALPHABET[n % 26] + str(n // 26)
```

Same question, same model, same repository. The first answer opens with the file name because the file said to. The second one never mentions where the code lives.

The difference is small, and it applies to every answer: CLAUDE.md changes the default behaviour without you asking each time.

What belongs in it

The documentation's own test is the best one: write down what you would otherwise re-explain. In practice that means adding a line when one of these happens.

• Claude makes the same mistake twice.
• A review catches something it should have known about this codebase.
• You type a correction you also typed last session.
• A new teammate would need the same context to be useful.

And what does not belong: anything that is a multi-step procedure rather than a fact. Those become skills, in the skills lesson, because a procedure only needs loading while it is being carried out.

Starting one

The video runs /init. Claude reads the project, drafts the file, and asks "Do you want to make this edit to CLAUDE.md?". After a yes, the preview shows guidance for Claude Code in this repository: what the bootcamp notebooks are for, that uv manages the project with uv sync, and which API keys the notebooks expect. From then on, every new session loads it first.

/init

Run it, then delete most of what it wrote. A generated file is a starting point, and the value of this file is inversely proportional to its length: every line is loaded into every session, so a hundred lines of vague advice costs you context and buys you nothing.

Related

• Previous: Sessions
• Next: Memory
• Reference: Claude Code docs