You add a rule to CLAUDE.md. Next week you switch a task to Codex, and it never reads the rule. You paste the same instruction into .cursor/rules. Now the same convention lives in three files, drifting apart at three speeds, and none of them is the place a new teammate would look to understand why the product works the way it does.
Every serious comparison of these files I have read argues about the same thing: how to make the agent write code in your style. Tabs or spaces, which test runner, which folder gets the new component. That matters, but it is the cheap half of the problem. The expensive half is where the product decisions live: why auth is stateless, why we never soft-delete, why this endpoint stays idempotent even though it complicates the handler. Those are the instructions that, when they go missing, cost you a rewrite. And a rules file is a bad home for them.
What each file is actually for
Let me separate the three, because they are not the same kind of thing.
AGENTS.md is the closest thing this space has to a neutral standard. It is a plain Markdown file at the repo root that any agent can read, defined openly at agents.md, and adopted across several tools rather than one vendor. Its job is the operational contract of the repo: how to build, how to run the tests, which commands are safe, what the layout is. It is agent-agnostic on purpose, which is exactly why it is the right place for facts that are true no matter who executes.
CLAUDE.md is Anthropic’s convention for Claude Code, and it is genuinely useful when Claude Code is your executor. Anthropic documents it in their Claude Code best practices, and it can carry per-directory context, tool permissions, the small rituals a session needs. The catch is in the name. It is Claude’s file. The moment you route a task to another engine, it goes unread.
Cursor rules (the .cursor/rules directory) are the same idea bound to Cursor, with more structure around when each rule applies. GitHub Copilot has its own version too, repository custom instructions. Good inside that tool. Invisible outside it.
So the real map is: one open standard for the operational facts, and a set of vendor files for tool-specific behavior. None of them was designed to be the memory of your product.
The line that decides where a rule goes
Here is the test I use. For any instruction you are about to write down, ask: is this how the repo works, or why the product decided something?
- How the repo works is stable, verifiable, and true for every agent. “Run
make testbefore you claim done.” “Migrations live indb/migrate.” “Never edit generated files.” This belongs in AGENTS.md, because it is the operational contract and it should travel to whatever engine you run. - Why the product decided something is a decision with a reason and a blast radius. “We keep the payment webhook idempotent because the provider retries.” “We do not cache the balance because a stale balance is a support ticket and a refund.” That is not a coding convention. It is the product contract, and it has no business living in a file that one specific agent happens to read.
When you push decisions into a rules file, three things go wrong. The file grows until agents skim it. The reasons get compressed into commands, so the why is gone and only the what survives, which means the next person cannot tell a load-bearing rule from a leftover. And the decision now lives in exactly one tool’s format, so it does not survive a change of engine. I argued the general version of this in software specifications should be portable: the artifact that carries a decision has to outlive the tool that read it.
Rules files are conventions. Decisions are contracts.
A convention tells an agent how to fit in. A contract tells it what it is not allowed to break. Rules files are built for the first job and quietly fail at the second.
The failure is quiet because nothing errors. The agent reads the rule that is still there, follows it, and produces a green build against an instruction that stopped being true two sprints ago. That is the whole subject of your rules file is lying to your agents: a stale rule does not throw, it just misleads, confidently. A decision that only lives as a line in CLAUDE.md has no reason attached and no owner, so nobody notices when reality moves past it.
A contract behaves differently. It carries the reason, it travels with the task instead of sitting in a global file every agent half-reads, and it is checkable. The acceptance criterion “balance is never served from cache” can be tested. The CLAUDE.md line “prefer fresh reads” cannot. One is a gate. The other is a vibe with good intentions.
What I actually keep in each place
This is the split I run day to day, operating agents across more than one engine:
| Instruction | Where it lives | Why there |
|---|---|---|
| Build and test commands | AGENTS.md | operational, engine-agnostic |
| Repo layout, safe commands | AGENTS.md | true for every agent |
| Claude-specific tool permissions | CLAUDE.md | only Claude Code reads it |
| Cursor rule scoping | .cursor/rules |
only Cursor applies it |
| “Why we never soft-delete” | the spec / decision record | it is a decision, with a reason |
| Acceptance criteria for a change | the task contract | it has to be verifiable and travel |
The rules files stay small and operational. The decisions live in artifacts that persist outside any one session, carry their reason and can be checked, close to the task that needs them. When I route the same job to a different model, as in routing every task to the right engine, the operational file might get re-read by the new engine and the decision travels with the work regardless. Nothing important is trapped in one vendor’s Markdown.
Where PaellaDoc fits
This is the same argument as the rest of what I build. A rules file is fine as an operational note and dangerous as a product memory, because the product contract has to sit above any single agent or it is not a contract, just a setting you rent until the tool changes. PaellaDoc keeps the decisions, the acceptance criteria and the reasons as first-class artifacts that travel with the task and get checked at the gate, whichever engine writes the code. The AGENTS.md still tells the agent how to build. The contract decides whether what it built counts. That division of labor is the whole runtime thesis: you are the runtime holding it together by hand, until something else does.
FAQ
Should I use AGENTS.md or CLAUDE.md?
Both, for different jobs. Keep the operational facts (build, test, layout, safe commands) in AGENTS.md so every engine can read them. Keep Claude-specific behavior in CLAUDE.md if Claude Code is one of your executors. Do not duplicate the same content into both, or you inherit the drift problem the moment one copy changes.
Where should product decisions live if not in the rules file?
In an artifact that carries the reason and can be verified, close to the work it governs: a spec, a decision record, or the acceptance criteria on the task. Rules files compress decisions into commands and lose the why, and they are bound to one tool. A decision needs to outlive both the session and the engine.
Do I still need cursor rules if I have AGENTS.md?
If you use Cursor and want its scoping and per-glob application, yes, for tool-specific behavior. Just do not let it become the only place a real decision is written down, because it is invisible to every other agent you might route work to.