CLAUDE.md and AGENTS.md in the same project - how to avoid maintaining two files

Charles Hasse — Thu, 06 Aug 2026 16:04:57 +0000

I spent two weeks with a CLAUDE.md and an AGENTS.md saying different things about the same repository.

I found out the worst way: an agent did exactly what the rule forbade, and the rule was there. In the other file.

(abertura sugerida: confira se bate com a sua memória e ajuste para a sua voz antes de postar)

Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Use both in one project and you have two files describing how to work in your code, with nothing forcing them to say the same thing.

Why two drifting files cost you

The problem is not the duplication, it is how quiet it is. You add a new rule (never touch this folder, always run that command before committing) to whichever file was open, and forget the other. Two weeks later an AI agent does exactly what the rule forbade, and the error does not say "I read the old version of your instructions". It says something else entirely, and you go looking in the wrong place.

The more specific your rules, the worse it gets. Generic rules converge on their own; project rules do not.

How to keep both without duplicating the text

Pick one file as the source and have the other point at it. A three-line AGENTS.md does the job:

`# Project instructions

The rules for this repository live in CLAUDE.md. Read that file
first and follow whatever it says.`

It works because both tools read repository files on demand: the agent opens the one you pointed to and follows it. You get one place to edit, and the question "which of the two is right?" stops existing.

Does a symlink work?

It does, and it is the leanest option if your team is all Unix: ln -s CLAUDE.md AGENTS.md and the two become one file. The caveat is Windows, where symlinks depend on permissions and Git has to be configured to preserve them. If someone clones on Windows without that, the file becomes a one-line text containing a path, and the AI agent reads that as your instructions.

A text pointer has no such risk and costs three lines. That is what we prefer.

What to put in that file

The part that changes outcomes is not the format, it is the content. What pays off, from running six AI agents in one repository:

· What NOT to touch, with the reason attached. "Do not edit this file" gets ignored; "do not edit this file because it is generated by X and your change disappears on the next build" gets obeyed.
· The command that proves it is done. An agent with no completion criteria delivers when it feels finished. With the command written down, it runs it and fixes things before calling you.
· How work is isolated, if you run more than one agent at a time. Without it, two agents edit the same file and one of them loses the work.

What if the rules genuinely differ per tool?

It happens, and it is the one case where two separate files are justified: when the instruction is about the tool itself, not about the project. Keep the pointer to the shared rules and add only the tool-specific part below it. What must not happen is project rules living duplicated in both.

Does this apply to other AI agents?

It does, and it will get worse before it gets better: every new tool brings its own filename. One source file with pointers scales to however many appear, because adding another costs three lines instead of a copy of your entire manual.

How to confirm both are being read

Ask the agent. "Which project instructions did you load?" at the start of a session answers in a second, and beats guessing. It is worth doing right after you move folders around: an instruction file in a subdirectory is not always found from wherever the tool was launched.

I wrote the full version, with the parts that did not fit here:
https://canvascode.app/en/news/claude-md-vs-agents-md-in-the-same-project

DEV Community: Charles Hasse

CLAUDE.md and AGENTS.md in the same project - how to avoid maintaining two files