Rules files: AGENTS.md and CLAUDE.md

A coding agent starts every session with no memory of the last one. What it nevertheless knows about your project is in a file it reads by itself on start. Depending on the tool it is called AGENTS.md, CLAUDE.md or similar; the principle is the same everywhere: a text file in the project folder that is loaded into every session.

What belongs in it

The guiding question is: what can the agent not find out by itself? It can see folder structure and programming language. It cannot see your intentions.

• Purpose in two sentences. What is this, for whom, in what state – live or prototype?
• Commands. How to build, test, start. Verbatim, ready to copy.
• Departures from the usual. Everything where the obvious assumption would be wrong: “British English”, “no client-side JavaScript”.
• Prohibitions with a reason. What must never happen, and why.
• Definition of done. Which checks must pass before something counts as finished.
• Signposts. Where the detailed documentation lives – the pointer, not its content.

# Project rules

Online store front end, LIVE. Every change on main is public at once.

## Commands
- Check: npm run build && npm test
- Start: npm run dev

## Rules
- Never work directly on main, because no review happens there.
- Copy in British English.
- A change is done only when build and tests are green.

Deployment details: docs/OPERATIONS.md

What clogs it

Every line is read in every session and pushes something else out of the model’s attention. So three things do not belong in it:

• What is in the code. A list of all files is out of date the day after it is written.
• History. How things used to be matters only for a specific question. That belongs in a document of its own.
• Credentials. Never. Only the place where they are kept.

As a guide: whatever grows beyond a hundred lines is split into topics the rules file merely points to.

Give reasons instead of shouting

“NEVER force-push!!!” is obeyed – for exactly that command. “Never force-push, because others work on the same branch” is also obeyed when the agent could achieve the same effect by another route. The reason turns a single rule into a principle the agent transfers to cases you did not think of.

Three levels

Most tools read rules from several places and layer them: your personal rules for all projects, the project file in the main folder and, where needed, subfolder files for one area. Personal is how you want to work. Project-level is what applies to everyone working on the project – that file belongs under version control.

Upkeep in two rules

If the agent makes the same mistake a second time, a line is added. If a line has not been needed for three months or is no longer true, it goes. A rules file that only grows eventually gets skimmed – by models as much as by people.

Whatever turns out to be a fixed procedure belongs not in the rules file but in a skill. That is material for the expert path Running agents.