CLAUDE.md example: the project rules file that made 445 pull requests mergeable
Every agent session on my build starts by reading one file. It is the only thing that is true in every session, for every agent, after every context reset, and it is why 445 pull requests from eight agents could be merged by one person without reading most of them line by line. Here is what is in it, why each part exists, and a neutral example you can adapt.
What it is for
An agent has no memory between sessions. Whatever you told it yesterday is gone, and whatever a colleague agent learned this morning never existed for it. The rules file is the fix: the set of facts and rules that every session inherits. If it is not in the file, for the agents it does not exist. That is the design principle, and it cuts both ways: the file has to carry everything that matters, and nothing that matters may live only in a conversation.
The structure
Seven sections, in this order, because the order is how an agent reads it.
| Section | What it holds | Why first readers need it |
|---|---|---|
| Thesis | One sentence: what the user can trust the product for. One principle: the model proposes, a person decides, the system records who | Every scope question resolves against it |
| Read before touching anything | The five documents that are the source of truth: architecture, domain model, permissions matrix, design, decisions | Stops an agent inventing a requirement that is written elsewhere |
| Stack, closed | The exact stack, and the sentence "nothing else". Amendments listed by decision id | Agents propose infrastructure for free; this is what says no |
| Hard rules | Numbered, each with the date and the incident that produced it | A rule with a reason is followed; one without is argued with |
| Task states | The only words a task may be reported in: VERIFIED, IMPLEMENTED, NEEDS_REVIEW, BLOCKED, DECISION_REQUIRED | Removes "done" as a word, because it means nothing |
| Escalation format | How an agent asks a human a question: a stable id, three options, a recommendation, what happens if nobody answers | Decisions take seconds instead of conversations |
| Conventions | Where files go, how commits are written, which language in code and which in the interface | The boring consistency that makes diffs readable |
A neutral example of the rules section
These are not my rules; they are the shape of my rules, on a product that does not exist.
## Hard rules
1. Build nothing for a hypothetical need. Every piece of
infrastructure names the MVP requirement it serves. No
requirement, no build.
2. Never real data. Seeds, tests and screenshots use synthetic
records only.
3. Never secrets in the repository. Production secrets live in
the deployment environment and are never in an agent's reach.
4. Row level security on every new table, with a test that runs
as the role that must not get in. No test, no pull request.
5. What a role must not see does not leave the server. Hiding a
column in the frontend is not a guarantee.
6. No model output writes to an entity. It writes to a proposals
table; a person decides; the application applies it and logs
who decided.
7. Never say a test passed if it was not run. Never say a
migration is safe without reading it. Never invent a
requirement. (Added after an agent reported a suite green
that had skipped every integration test.)
8. No agent declares an external fact. A script produces it as
JSON and the agent interprets it. "CI is green" and "the
preview works" are not sentences; a run id and a URL are.
9. A test never asserts a behaviour as "existing, not introduced
by this ticket". A suspected bug becomes a ticket and the test
is marked pending, never green. (Added the day it happened
three times.)
Notice what each rule has: a boundary that can be checked, and, for the ones that came from incidents, the incident. Rule 7 exists because a test suite reported success with a hundred skipped files. Rule 9 exists because a comment saying "existing behaviour" sat on top of a bug for three weeks and the green test made the fix look like a regression. The reason is not decoration. It is what makes an agent, two weeks later, recognise the same situation in a different shape.
The escalation format, because it is the part people miss
Agents stop at real decisions. If they do not have a format for stopping, they either guess or they write three paragraphs. Mine is fixed:
DECISION 014-3: the question in one line
A) option B) option C) option
RECOMMENDATION: B. WHY: one line. IF UNDECIDED: what happens
DECISIONS REQUIRED: 014-3, 014-4
ACTIONS FOR YOU: open the preview at <url> and say what is off
I answer with the id and a letter. The lead records the answer in the decisions log, citing the id. Over seven weeks that was more than 170 decisions, most answered in under a minute, every one of them findable later. Without the id, a decision lives in a chat and the next session does not know it was taken.
How the file grows
It started at 12 rules. It is 29 now. Every one of the 17 additions has a date, and most have a one line incident. The file never shrinks; a rule that stops applying is struck through with the reason, so the next person knows why it was there. A lessons table lives next to it, one line per incident, with the rule it left. That table is the real history of the build, and it is more useful than the commit log.
This is step 2 of how to build an MVP with AI agents. It follows scoping as invariants and feeds the ticket template. The gates the rules refer to are in why a green check is not proof.
Copy the template: CLAUDE.md template, with a prompt to use it and its changelog.
Questions people ask
What is CLAUDE.md?
The file at the root of a repository that Claude Code reads at the start of every session. It is where the rules of the project live: what the product is, which stack is allowed, what an agent may never do, and how it reports. Other agent tools read an equivalent file under another name.
How long should a CLAUDE.md be?
Mine is about 300 lines after seven weeks, and every line is there because of something that happened. Shorter is better only if nothing is missing. The test is not length, it is whether a fresh agent with no memory would make the same mistake twice.
Should CLAUDE.md contain code style rules?
A few, where a linter cannot catch them. Most style goes in the linter and the formatter, and the rules file says 'the linter decides'. The file is for decisions a machine cannot take: what the product is for, who decides what, what counts as proof.
Can I copy your CLAUDE.md?
You can copy the structure, which is in this article. You cannot copy the rules, because each one is the answer to an incident on a specific product. A rule you did not earn is a rule the agents will talk you out of in the first week.
Working on something like this?
This is how I build products with AI agent teams, from scope to production. Discuss a product idea → Or email me.