A markdown file in a repository is not documentation. It is an instruction set for a reader with no context, infinite patience, and a tendency to take you literally. Most .md files fail because they are written for a colleague who can ask follow-up questions. Agents cannot.
The first rule is to write constraints, not descriptions. A sentence like "we use Tailwind for styling" is trivia. A sentence like "never write a separate CSS file, all styling happens through Tailwind classes" is a rule an agent can follow. Every line should survive the question: what would someone do differently after reading this?
Keep the root file short. CLAUDE.md at the top of the repo should fit on one screen: what the project is, the three commands that matter, and the rules that apply everywhere. Anything scoped to a package belongs in that package. An agent working in apps/api should not wade through conventions for the marketing site.
Structure beats prose. Agents parse headings, lists, and code blocks far more reliably than paragraphs. If a rule has an exception, put the exception on the next line, not three sections later. If a workflow has an order, number it.
Write the why only when the rule would otherwise be reverted. "Use the static font cuts here, satori cannot parse variable fonts" saves the next reader from a confident wrong fix. A comment that just restates the rule is noise, and noise trains readers to skim.
Test your files the way you test code. Give a fresh session a task, watch where it goes wrong, and patch the file, not the session. The .md file is the product. Every correction you type twice belongs in it.
The last habit is pruning. Stale instructions are worse than missing ones, because they are followed. When a rule stops being true, deleting it is a contribution.
Workbench Notes · Makers of Legora