CLAUDE.md that gets followed

Every session starts with an empty conversation. CLAUDE.md is the file that stops you explaining the same things every morning.

It is a markdown file in your project. Claude Code reads it at the start of every session, before you type anything, and it stays loaded rather than being summarised away when the conversation gets long.

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. Here is the same question asked twice, 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.

It is a small difference and that is the point. CLAUDE.md changes the default behaviour of every answer, quietly, without you asking for it 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 lesson 13, because a procedure only needs loading when it is actually being done.

Starting one

/init

It reads the project and writes a first CLAUDE.md for you to edit. Treat what comes back as a draft rather than a result.

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.