Open a repository that has been worked on with AI for a few months and you will often find more than one file telling agents how to behave. An AGENTS.md. A CLAUDE.md. Perhaps a GEMINI.md, or something under .github or .cursor. Each was added by whoever was using that tool at the time, and each was true on the day it was written.
The files are not the problem. The problem arrives later, when they no longer say the same thing and nobody notices, because no single person reads all of them.
Checked in October 2026, and worth checking again against your tool’s own documentation before you rely on it: support for AGENTS.md as a common format has been spreading, and several tools now read it alongside their own file. Treat the table as a starting point rather than a settled fact.
AGENTS.md exists to stop this proliferation, and it is the right thing to write first. But a tool that only reads its own file will not see it, so most teams keep at least two: the open format, and whatever their main tool insists on.
That leaves you maintaining the same instructions twice. Which is fine, right up until the day somebody updates one of them.
Two instruction files disagreeing is not a tidiness problem. It means two agents are confidently doing different things, and both believe they are following your rules.
A realistic example: AGENTS.md says the project uses PostgreSQL and that the schema must not change without asking. CLAUDE.md, written two months earlier, still describes the MongoDB prototype. One agent proposes a migration; another refuses the same change. Neither is wrong about its instructions.
Nobody catches this by reading, because reading one file never reveals that another contradicts it. You catch it when something has already been built the wrong way.
Pointing CLAUDE.md at AGENTS.md with a symlink does work in some setups and removes the duplication entirely. It is worth trying. Be aware that symlinks behave differently on Windows, that some tools resolve them and some do not, and that a reviewer looking at the repository on the web may not see what is going on. Test it with the tools your team actually uses before relying on it.
The only reliable way is for something to compare the files for you and tell you when two of them say incompatible things. That is what Canonly does: it reads your instruction files alongside the rest of your project, finds pairs that are about the same subject, has a model decide whether they genuinely disagree rather than merely overlap, and flags both until somebody settles it.
Its ready-for-AI check reports the specific case this guide is about — "your AI instructions disagree" — with a link to the pair, because that is the one most likely to cause work to be done twice.