Before you copy your CLAUDE.md into an AGENTS.md, answer a narrower question: does Claude Code actually need different instructions in this repo than Codex or Cursor does? In most projects the honest answer is no. The test command is the same, the directory layout is the same, the "don't touch the generated client" rule is the same. The CLAUDE.md vs AGENTS.md problem is usually not a content problem at all. It is a discovery problem: each assistant looks for a file with a particular name, finds nothing, and proceeds on guesses.
That reframing changes what you build. If the content is identical, you need one source of truth and a way for both tools to find it. If the content genuinely differs, you need two files and a rule about which one owns what. Those are different setups, and picking the wrong one is how you end up with two instruction files that drift for three weeks before anyone notices.
CLAUDE.md vs AGENTS.md: what each name assumes
Both files do the same job: a Markdown project instructions file at the repo root that an assistant reads before it starts working. The difference is in the convention around them, not the format.
CLAUDE.md is Claude Code's name for it. It tends to be written as if one assistant will read it, and in practice it collects things that are specific to how you use that tool: which commands to run unprompted, how much to do before checking in, what to never edit without asking.
AGENTS.md is the name the broader agent ecosystem converged on, and Codex and several other tools look for it. The convention is deliberately tool-neutral, which means an AGENTS.md file is usually written for "whatever agent is reading this" rather than for a named product. It also commonly supports nesting: a file in a subdirectory applies to work inside that subdirectory.
Support for the other name moves. Some assistants have added fallbacks, some read both, some read only their own. Before you rely on a tool picking up a file it does not natively own, check its current docs rather than assuming, because the failure is silent. The assistant does not announce that it found nothing.
The practical consequence: the file name is a lookup key owned by the tool, and the content is a document owned by you. Treat those as separate decisions.
The one-file setup that covers most projects
Start with a single real file and make the second name point at it. Two versions of this work.
The simplest is a symlink:
ln -s CLAUDE.md AGENTS.md
One file to edit, both lookups resolve. The caveats are real though: symlinks behave badly on Windows checkouts, some tools read the link target as text rather than following it, and a reviewer scanning the repo may not notice which file is the real one. If your team is all on macOS or Linux and your tooling handles it, this is the cleanest option.
The alternative is a thin pointer. AGENTS.md holds only enough to be useful on its own:
# Project instructions
The full instructions for this project are in `CLAUDE.md` at the repo root.
Read that file before making changes. It is the source of truth for commands,
conventions and constraints, regardless of which assistant you are.
Quick version:
- Install: `pnpm install`
- Test: `pnpm test` (run before proposing a commit)
- Do not edit `src/api/generated/` by hand
A pointer is more honest about what it is, survives any platform, and still gives an assistant that will not follow the link something to work with. The risk is that the assistant reads the pointer and never opens the target. That is the same class of problem covered in why your assistant ignoring CLAUDE.md isn't a loading bug: a file being present is not the same as a file being used. Which is why the quick version at the bottom matters. Put the three or four rules that cause the most damage when broken directly in the pointer.
Which file should be the real one? If Claude Code is your primary tool, keep CLAUDE.md as the source and point AGENTS.md at it. If you have a mixed team or you expect to add more agents, make AGENTS.md the real file, since it is the name more tools will look for over time, and have CLAUDE.md point there.
When a second file actually earns its place
Fork the content when two assistants need to behave differently, not when they need the same instructions twice. A few cases where that is real:
Tool-specific operating instructions. How much autonomy you give an agent before it checks in with you, whether it should run the whole suite or a targeted test, which slash commands or custom workflows exist. These are facts about the tool, not about the project, and they do not belong in a shared file.
Permission and safety boundaries. If one assistant runs in a sandbox where it can execute anything and another runs against your real machine, the rules about destructive commands are not the same rules.
Scope of work. Some teams use one assistant for implementation and another for review or exploration. The instructions for "write the code the way we write code here" and "find the problem and explain it, do not patch it" are different documents by nature.
What almost never justifies a fork: build commands, directory conventions, naming rules, dependency policy, test requirements, architectural constraints. That is project knowledge. Duplicating it is how you get a repo where CLAUDE.md says pnpm test and AGENTS.md still says npm test six months after you switched.
The split that holds up looks like this:
AGENTS.md # shared: everything about the project
CLAUDE.md # pointer to AGENTS.md + Claude Code specifics
.prjcontext/
instructions/ # longer-form instruction docs if the root file grows
memory/ # decisions, open questions, current state
sessions/ # the conversations worth keeping
Keep the shared file the long one and the tool-specific files short. A CLAUDE.md that is fifteen lines of genuinely Claude-specific instruction plus a pointer is easy to review. A CLAUDE.md that is a 200-line near-copy is not.
Keeping two instruction files from quietly contradicting each other
Contradiction is the real cost of a fork, and it is slow. Nobody edits both files on the same day. Someone changes the lint rule, updates the file their assistant reads, and the other file keeps teaching the old rule to the other assistant.
Three habits make this manageable.
Write an ownership line at the top of each file. One sentence: "This file contains Claude Code specifics only. Project conventions live in AGENTS.md." It costs nothing and it tells the next person (and the next assistant) where to make the edit.
Never let a fact exist in two places. If the test command appears in both files, one of them is going to be wrong eventually. The exception is the short quick-reference block in a pointer file, and if you use one, accept that it needs a review whenever those commands change.
Review both files when you change either. In practice this means opening the diff and asking whether the other file now claims something false. A broader version of this discipline, including how to keep memory and session context aligned across tools, is in the shared context setup for multiple assistants on one codebase.
It also helps to keep instructions thin in the first place. Most bloated instruction files are bloated because they contain project state, not rules. If your file is drifting toward a changelog, the split described in CLAUDE.md and project memory will cut it down faster than any reorganisation of file names, and there is more on writing the rules themselves in the guide to project instructions your assistant follows.
Making the setup survive the next machine
Whatever split you land on, it only works if both files travel with the project. The common failure is a CLAUDE.md that is committed and an AGENTS.md that someone created locally when they tried Codex for an afternoon, which means the next person to add that tool starts from a blank file and reinvents half the rules.
Instruction files belong in version control alongside the code. Beyond that, we built PrjLab so the rest of the context travels too: a repository holds your files plus .prjcontext/instructions/, .prjcontext/memory/ and .prjcontext/sessions/, with CLAUDE.md and AGENTS.md at the root recognised as instructions. prj push creates an immutable version with a line diff, and prj clone on another machine brings the whole picture down, so an assistant added later reads the same committed instructions instead of a fresh guess. If that is the gap you are looking at, the getting-started guide walks through the first push.
FAQ
Do I need both CLAUDE.md and AGENTS.md? Only if the assistants reading them need different instructions. If the content is the same, keep one real file and make the second name resolve to it, either with a symlink or a short pointer file that restates the handful of rules that matter most.
Can AGENTS.md replace CLAUDE.md entirely?
It can be your single source of truth, but whether Claude Code finds it without a CLAUDE.md present depends on the version you are running. The safe setup is to keep a CLAUDE.md at the root that points to AGENTS.md, which costs you five lines and removes the uncertainty.
What goes in AGENTS.md that does not go in CLAUDE.md?
In a one-file setup, nothing: the shared file holds all project conventions. In a forked setup, AGENTS.md holds the tool-neutral project knowledge (commands, layout, constraints, conventions) and each tool-specific file holds only how that tool should operate: autonomy level, permissions, custom commands, scope of work.
Will having both files confuse an assistant? Not if they do not disagree. An assistant that reads both a pointer and its target sees consistent instructions twice, which is harmless. An assistant that reads two files claiming different test commands will pick one, usually without telling you.
Does AGENTS.md work in subdirectories? The convention supports nesting, with the nearest file applying to work in that directory, and several tools implement it. It is useful in a monorepo where each package has its own build and test commands. Confirm the behaviour in your tool's docs before you rely on it, and keep the root file as the general case.
