Angel Espinoza on why a per-project CLAUDE.md (plain rules for the AI assistant) often beats repeating context every session—write the rules down once, not every time.
The Markdown file
The most useful file in most of my projects is not code. It is a plain text file named CLAUDE.md, one per project, that tells the AI assistant the rules of that project before I have said a word that session.
A markdown file is just text with light formatting, headings, a bulleted list, maybe a code sample. Nothing about it looks special. What makes it different here is that an AI coding assistant reads it automatically at the start of a session and treats it as instructions, not documentation. I do not explain, every single time, that one project builds with a specific command, that another has no automated tests because everything gets checked by hand, that a third has a naming rule its API depends on. I wrote each of those down once, and the assistant already knows them the next time I open that project.
That is the part I did not expect going in. I assumed the value was answering questions faster. The real value has been not repeating myself. A rule I would otherwise re-explain in every new conversation gets written down once, in a file that sits quietly in the project folder, and it holds.
It also means the rules are visible to me too. Six months from now I will not remember why one project's build works a certain way. The file will. Some projects get more than one: a charter that states what the project is actually for, a lessons-learned log for what broke and how it got fixed. Different purposes, same habit. Nobody has to carry it in their head.
Be Better! ...write the rules down once, not every time.