Write AGENTS.md rules that survive the session

You told it last week. It did it again.

You catch an AI agent doing something wrong, you say so, it apologizes and fixes it, and the next session it does the same thing as if the conversation never happened. For the agent, it never did happen. An agent opens every session with no memory of the last one, so whatever you said in chat is gone when the window closes, and you pay for the same mistake every time it comes back.

Picture a shop where the whole staff is new every morning. They're skilled and willing, but nobody who worked yesterday is here today. A shop like that runs on the closing checklist by the register, and every line on it came from a night something went wrong. The ice machine lid is on the list because someone left it up and the floor flooded. A line that says "be tidy" gets skipped. A line that says "lid down, because the floor flooded when it was left up" gets done, and the next shift can see from the door whether the lid is down.

Your agent is that crew, and the answer is that checklist, a plain text file named AGENTS.md at the project's root that the agent reads before it does anything else. A rule is earned by a failure, ends in a check that can fail, and lives where it loads every session. One project tested the middle part when it read back the closing notes from 148 of its sessions and sorted every repeated mistake by whether its rule ended in a check or in prose.

Earned by a failure

Don't write rules because they sound sensible. Sensible rules have no cost attached, so nothing in them says what skipping costs, and they get skipped. Write the rule the moment something goes wrong, and write the failure into it, what happened, why it seemed reasonable at the time and what it cost. The next agent will tell itself the same plausible story, and the rule has to name that story to interrupt it. Name what the mistake looks like from the outside too, because that's the tell the next session will actually catch.

The team that builds Claude Code, Anthropic's coding agent, runs the same rule on its own repo. Boris Cherny, who created Claude Code, puts it plainly. "Anytime we see Claude do something incorrectly we add it to the CLAUDE.md." His team's habit is to end every correction by telling the agent to write the rule itself. CLAUDE.md is the filename Claude Code looks for, and one line in it pointing at AGENTS.md means every tool reads the same rules.

When a mistake the rules already cover happens anyway, the answer is never that it was already written down. It was written down and it happened anyway, so the rule is in the wrong place, or worded so nobody reads it as an instruction, or missing its check. The failure is the evidence. Fix the rule, and don't blame the agent, because tomorrow's session is a different one.

Ends in a check that can fail

A rule that ends in "be careful," "double-check" or "make sure" fires on attention, and attention is what the failure already beat. A rule ends in a mechanism instead, a command to run, a string to search for or a test that fails. And prove the check can fail. Run it once against the thing it's supposed to catch and watch it fail, because a check that has only ever passed hasn't proven it can do anything else.

That reading of 148 session notes is where this comes from. Every kind of failure that had been given a mechanism stopped recurring. The prose-only rules recurred at least eight times after they were written, twice while the agent was quoting the rule it was breaking. The bar that came out of it is one line. A new rule has to name the step where it fires, and if no such step exists yet, it's written as a note to watch for the failure, and it doesn't get written as a rule.

One rule that project kept is about deleting a feature. It says the removal isn't done until everything that existed only to serve the feature goes too, including its styles, its helpers and the check that measured it. It fires at the commit that removes the feature, when the agent searches for anything still pointing at what was removed. And it names what it prevents, leftovers that sit as dead weight no later review will notice. Measured across three projects, the worst case was 1,190 leftover lines nobody had listed. It also names the tell, a deletion that looks complete. That covers three of the four lines taught below. What it leaves out is why the mistake looked reasonable, which is the line most rules skip.

Lives where it loads every session

A rules file isn't always one file. There's the one at the project's root that loads every session, there are smaller ones that load only when certain folders are touched, and there are documents the root file merely points at. Then there's the file that loads in every project on the machine, if your tool has one. A correction said in chat fires once. A note in a session's closing write-up fires once, tomorrow morning, and never again. A rules file at the project's root fires every session. A rule scoped to a folder fires every time a file in that folder is touched. Those are different distances, and a correction has to be filed at the distance the failure came from. If the mistake would have happened in any project, it goes in the file that loads everywhere. If it was about this project's deploy, it goes in the rule about deploying.

There's a test for the hardest case, which is a rule that could go in the always-read file or in a document the root file points at. Can the agent know it needs this rule before reading it? If yes, it can wait in that document, because the task itself will send the agent looking. If no, it has to load every session, because a rule behind a pointer only fires if the agent already suspects it needs it. That project learned it when a rule filed in a perfectly sensible on-demand document went unread for a whole session.

How to write one

Open the rules file at the distance your failure came from. Most often that's the one at the project's root, described in Stop your AI agent from forgetting your project between sessions. Write four lines in this order.

1. What happened and what it cost. One sentence, concrete enough that someone who wasn't there could picture it.
2. Why it was plausible. The story the agent told itself, because the next one will tell it too.
3. The mechanism. The command, the search, the check that would have failed, and the step in the session where it fires. Run it once against the failure so you've seen it fail. If no such step exists yet, write a note to watch for the failure instead, and turn it into a rule once the check exists.
4. The tell. What the mistake looks like from the outside, the moment before it lands.

Then, before you close the session, read the four lines as someone who wasn't there. If they can't picture the failure, the rule won't fire.

A rule's words come off only when a hook, a script your tool runs automatically at a fixed moment, or a test outside the file enforces the rule without them. They never come off because the list is long.

What you get and what you don't

The file grows a line per failure, and the agent stops repeating the mistakes you've written a check for. It won't stop the agent making new ones. The file is a record of what already went wrong, and it has nothing to say about tomorrow's first mistake.

The next time your agent does something wrong, don't correct it in the chat. Add the rule to AGENTS.md before the session ends.