The loop from yesterday worked because the agent was told exactly what to do; today is the file that means you stop re-explaining how your team works at the start of every session.
The first time I let a coding agent write a test for me, it handed back something that broke nearly every rule my suite has. A CSS class for a locator I had banned years ago. A cy.wait(3000) dropped on a race condition. No test ID, the selectors sitting inline in the spec, an assertion that the page loaded and nothing more.
It was not being careless. It simply did not know any of my conventions, because I had never told it. A coding agent writes whatever the codebase nudges it toward, and if your standards live in your head, it cannot follow them.
So I wrote my standards down once, in the one file the agent reads before it writes a line. For Claude that file is CLAUDE.md. Other agents read AGENTS.md, the cross-tool standard that Cursor, Codex, and Copilot look for. Same idea, different name. In the Day 0 triangle, this file is what the agent always knows.
Two rules decide whether the file does anything at all
- Keep it tight. The agent loads the whole file at the start of every session, so every line costs context. Keep it under roughly 200 lines. My first version was too thin and the tests stayed generic; the next was too long and the agent missed rules in the middle. Tight is the target.
- Make every rule checkable. “Write good locators” tells an agent nothing. “Use role, aria-label, or a data-* hook, never a CSS class or an nth-child chain” tells it exactly what passes and what fails.
You do not write this file by hand
The agent that will read the file already knows what a good rules file looks like, because it was trained on thousands of them. Your job is to bring the judgment of what good looks like, then direct it to draft, prove, and tune. The order I work in:
- Talk it out with a conversational AI first, so you get specific about what the suite should enforce.
- Mine your corrections.
- Have the agent read your suite and draft the file.
- Make it prove the file by writing and running real tests.
- Fold the fixes back in as new rules.
Step 2 is the one to start with, because the things you keep retyping are your highest-value rules, and the agent already remembers them:
Based on everything you know about how I work and every
correction I have given you, list the things I correct you
on the most. Group them so I can turn each into a checkable
rule.
Copy it. What comes back are the rules that live in your head as “not this again”, the ones you would never have thought to write down.
The fence at the bottom
My file ends with a Never-generate block, and it is the part I use most. Eight things that should never appear in a generated test:
- a fixed-time sleep of any kind
- a raw framework command in a spec
- an inline selector or inline text
- a brittle selector: positional, nth-child, or a generated class
- hardcoded data that rots when the environment resets
- a test that depends on another test’s state
- an exact-count assertion against live data
- an empty test ID
A fixed-time sleep is the first line because it is the first thing I once removed by hand, hundreds of times, from a suite people had stopped trusting. Putting it in the fence means the agent never writes the flake I would only catch later. Keep the list. It comes back on Day 8 as your review checklist.
One gotcha, and one honest limit
The gotcha: Claude Code does not read AGENTS.md. If your repo already has one, make the first line of your CLAUDE.md an import, @AGENTS.md, or symlink the two, so the files never drift apart.
The honest limit: a rules file shapes behaviour. It does not enforce anything. It is context the agent is strongly nudged by, not a wall it cannot climb. For the non-negotiable few, back the rule with a lint rule or a CI check so a spec that violates it cannot merge. A rule you are not willing to let block a merge was never really a rule. It was a preference.
Try this today
Run the mine-your-corrections prompt in whichever AI you use most, and turn the top three answers into checkable rules. If you want the full file to start from instead of a blank page, mine is free, ready as a CLAUDE.md and an AGENTS.md: AI test automation standards. The whole build story, with every step and prompt, is in write a CLAUDE.md for your test suite.
Tomorrow: the second corner of the triangle, for the procedures that do not belong in this file.