You wrote an AGENTS.md. The agent read it, then edited a generated file anyway, or ran the wrong test command, or reformatted a module you had explicitly fenced off. So you added a line. The next run ignored a different one. Now the file is two hundred lines written in good faith and you have stopped believing any of them are load-bearing.
That is not the agent being careless. Most AGENTS.md files I have read, including several of my own, are written as though the reader were a new teammate who will ask a follow-up question when something reads ambiguously. This reader never asks. It fills the gap with something plausible and keeps going, which is the same failure that shows up everywhere else you hand an agent an underspecified contract.
The part this piece does not re-argue
There is a genuine argument about which decisions belong in a rules file at all, and it already has a home in where your decisions should actually live. The compressed version: operational facts about how the repo works belong in the rules file, and product decisions with their reasons belong in a contract that travels. Procedures that only apply sometimes are a different channel with a different cost, and the invariants an agent must see before it writes anything are a category of their own.
Assume you have already decided a line belongs in AGENTS.md. This is about how to write it so it survives contact with a run.
Put it where the agent is already looking
AGENTS.md is a plain Markdown file at the root of the repository, and for a single-package project that is the whole placement question.
Monorepos are where people get this wrong, and the wrong move is to write one root file that tries to describe every package. It grows past the length where anything gets followed, and worse, most of it is irrelevant to any given task. An agent working in the API package pays attention to build instructions for the mobile client for no reason at all.
Nesting is the supported answer, and the standard is explicit about it: “Large monorepo? Use nested AGENTS.md files for subprojects”, with the instruction to “Place another AGENTS.md inside each package.” Put a short one at the root for what is true everywhere, and a second inside each package for what is true only there. Root file: the language versions, the monorepo tool, the commit conventions, the directories nobody should touch. Package file: how this package builds, how its tests run, what it must not import. When an agent works inside packages/api, the file sitting next to the code is the one describing the code it is editing.
The conflict rule is worth knowing before you need it, because it decides how you split content. Per the standard’s FAQ, “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.” So a package file does not need to restate the root file to beat it on its own turf, and nothing you write in either survives a direct instruction in the session. That second half is a useful reminder that a rules file sets defaults rather than guarantees.
The rule of thumb that keeps this from becoming its own maintenance problem is that a fact lives in exactly one file. If the root file and the package file both explain how to run tests, one of them will be wrong within a month, and you will not find out which until an agent follows it. This is the same drift mechanism that makes rules files quietly start lying to you, and duplication is the fastest way to trigger it.
The shape, and why the order is not arbitrary
Four sections cover almost everything, and the order matters because agents, like people, weight the top of a document more heavily than the bottom.
Commands go first. How to install, how to build, how to run the tests, how to run a single test. These are the lines an agent needs on almost every task, and the ones where being wrong costs the most, because a wrong test command produces a confident claim of success with nothing behind it.
Boundaries go second. What must not be touched, what must not be imported, what is generated and will be overwritten. Boundaries are worth more than instructions when the thing reading them can produce plausible code fast, and they are the section people write last and shortest.
Conventions go third. Naming, error handling, the patterns this repo has settled on. This is the section that bloats, and the one to cut first when the file gets long.
Layout goes last. Where things live. It is genuinely useful and genuinely the least urgent, because an agent can discover most of it by reading, whereas it cannot discover your test command by reading.
Every line has to be capable of being wrong
This is the test that changed my own files more than anything else on this list.
Take each line and ask whether something in the repository could prove it false. “Run pnpm test before claiming done” can be wrong, because pnpm test either exists or it does not. “Migrations live in db/migrate” can be wrong, because that path resolves or it does not. Both are checkable, and an agent can act on them without interpretation.
Now the other kind. “Write clean, maintainable code.” “Follow best practices.” “Be careful with the auth module.” Nothing in the repository could ever contradict these, which means an agent cannot tell them apart from a preference, and it will treat them as one. They are the lines you were sure you had written down, and they are why you feel unheard.
“Be careful with the auth module” becomes useful the moment you say what careful means: do not change the session expiry, do not add a dependency to that package, run the auth integration suite before claiming done. That is three checkable lines replacing one aspiration, and it is longer, which brings up the ceiling.
The length ceiling, and how to respect it
A rules file is loaded on every call, so every line is budget you spend on turns that never needed it. That is the mechanical cost. The human-shaped cost is worse: past a certain length the file stops being read carefully and starts being skimmed, by agents as much as by people.
I aim for something a person would read without scrolling more than a screen or two, and treat crossing that as a signal rather than a failure. When a root file gets long, the content usually wants to move rather than shrink. Package-specific facts want their own file. A procedure that applies to one kind of task wants to be a skill. A decision and its reasoning wants to be in the spec, where it can carry the why that a rules file compresses out.
Pruning is not tidying. Every rule you delete is one fewer thing an agent can misapply, and stale rules do more damage than missing ones, because a missing rule produces a question and a stale rule produces confident wrong work.
Write the first draft by reading the repo, not from memory
The reason most rules files contain aspirations is that they were written from memory, in one sitting, by someone describing the repo they intended to build.
Better: have an agent read the repository and draft the file from what is there. The package manager it actually uses. The test command in the CI config. The directories that are generated. Then cut hard, because that draft will be too long and too descriptive, and it will contain facts that are true but that no agent needed to be told.
The parts you write by hand afterwards are the boundaries, because those are the only things not inferable from the code. Nothing in the repository says “do not touch the payment integration without talking to me first.” That knowledge lives in your head until you write it down, and it is the highest-value content in the file.
Then check it the way an agent would. Run every command. Resolve every path. A rules file that has never been executed is a hypothesis.
Where PaellaDoc fits
The reason these files drift is that they are written once and maintained never, while the repository they describe changes weekly. PaellaDoc keeps the operational contract next to the code and the run evidence in a local model, so the commands and boundaries an agent reads can be checked against what the repository does now rather than what it did the day someone wrote them down. The file stays short because the reasoning behind each rule lives in the contract instead of being compressed into a line that will outlive its reason.
FAQ
Where do I put AGENTS.md in a monorepo? A short one at the root for what is true across all packages, and one per package for what is true only there. Keep each fact in exactly one file, because duplicating build or test instructions across two files guarantees that one of them goes stale without warning.
How long should an AGENTS.md be? Short enough to be read rather than skimmed, since it loads on every call. When it grows past a screen or two, the fix is usually to move content out rather than compress it: package facts to a nested file, occasional procedures to a skill, decisions and their reasons to the spec.
Why does my agent ignore parts of my AGENTS.md? Usually because those parts cannot be checked against anything. Lines like “write clean code” or “be careful here” have no observable meaning in the repository, so they get treated as preference rather than constraint. Replace each one with the specific commands, paths or prohibitions it was standing in for.
Should I keep both AGENTS.md and CLAUDE.md? Only if they carry different content. The failure is copying the same operational facts into both, which doubles the maintenance and guarantees divergence. Which content belongs where is the subject of the comparison piece.