Your rules file is instructions, not documentation

Most of the rules files I see are written for people. Descriptive, hedged, polite. "We generally prefer named exports." "The team tends to use Prisma."

Written like that, they get treated as background reading. Written as instructions — "Use named exports." "Use Prisma. Never raw SQL." — they get followed.

Same content. Different mood. Materially different output.

This is less mysterious than it sounds once you remember what the model is doing. It is completing a document, not attending a team meeting. A described preference is information about a team. An instruction is a thing to do.

What earns its place

The architecture, in four lines. Framework, database, styling, tests. Not a paragraph each — a line each.

Conventions that have a wrong answer. Export style, response shape, where things live. The test is whether a reasonable person could do it differently and be wrong for your codebase. If both answers are fine, it does not need to be in the file.

The patterns you would otherwise re-explain every session. How auth is checked, how the database is imported, how validation is done. These are the lines that earn their keep most obviously, because you can feel the cost of their absence.

What does not earn its place

History. Aspiration. Anything a new human colleague would need but the model does not — team structure, who to ask, why the project exists.

Rationale is the one exception worth keeping, and only where a convention departs from the tool's default. One line of why, so the convention does not get generalised into places it was never meant for. A rule with no reason given tends to get applied too widely.

This is not a README. Treating it as one is why so many of them quietly stop working.

Two rules I hold to

Keep it under about 200 lines. That is Anthropic's own published number for CLAUDE.md, and the stated reason is the one that matters: longer files consume more context and get followed less. Cursor's equivalent limit is 500 lines per rule. Either way, you are carrying the whole file on every single turn, whether or not it was relevant to the question — so every line is a line you pay for continuously.

Write it in the imperative. Not "we prefer", but "use". Direct instructions are followed more reliably than described preferences.

The failure mode nobody plans for

A rules file that is out of date is worse than no rules file at all.

A missing file means the model guesses, and you can see it guessing. A stale file means the model confidently instructs itself to be wrong, before you have typed a word — and it does so with your authority behind it. You will spend the session correcting something you wrote three months ago and forgot about.

So the maintenance rule matters more than the authoring rule: when you change a convention, change the file in the same commit. A rules file is part of the codebase, not a note about it.

How to tell if yours is working

Two checks, both cheap.

The removal test. Delete a line and see whether anything changes. If nothing does, the line was decoration — either it was never being followed, or the model would have done it anyway.

The first-turn test. Open a fresh thread and ask for something small and conventional. If the output already matches your house style without you asking, the file is working. If you find yourself adding "and use named exports", that line is not landing, and making it more polite will not help.

Where to go next

• The rules-file template — the structure above as something to copy, with the leave-out list
• System Prompts & Rules Files — the full lesson
• Context Management — persistent context, and why a file the tool reads every session is the cheapest form of it