Inigo AnguloContact
Work01How I think02Lab03Writing04
Writing

CLAUDE.md example: the project rules file that made 445 pull requests mergeable

Inigo AnguloNovember 4, 20268 min readBuilding with AI agents

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.

SectionWhat it holdsWhy first readers need it
ThesisOne sentence: what the user can trust the product for. One principle: the model proposes, a person decides, the system records whoEvery scope question resolves against it
Read before touching anythingThe five documents that are the source of truth: architecture, domain model, permissions matrix, design, decisionsStops an agent inventing a requirement that is written elsewhere
Stack, closedThe exact stack, and the sentence "nothing else". Amendments listed by decision idAgents propose infrastructure for free; this is what says no
Hard rulesNumbered, each with the date and the incident that produced itA rule with a reason is followed; one without is argued with
Task statesThe only words a task may be reported in: VERIFIED, IMPLEMENTED, NEEDS_REVIEW, BLOCKED, DECISION_REQUIREDRemoves "done" as a word, because it means nothing
Escalation formatHow an agent asks a human a question: a stable id, three options, a recommendation, what happens if nobody answersDecisions take seconds instead of conversations
ConventionsWhere files go, how commits are written, which language in code and which in the interfaceThe 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.

Kit

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.