AGENTS.md, CLAUDE.md and Cursor rules: one set of instructions
Put the shared instructions in one AGENTS.md at the repository root. Codex reads AGENTS.md files before doing any work, Cursor picks it up automatically from the project root, and Claude Code can read that in place of a CLAUDE.md. When a Claude Code session is not reading AGENTS.md directly, add a CLAUDE.md beside it that holds an @AGENTS.md import, so every tool still shares one file.
Reviewed November 2026
Which file does each agent read?
Each tool documents its own file names. The native names matter when you want an instruction that only one tool sees.
- AGENTS.md itself is described as a README for agents, a predictable place for context and instructions, and it is just standard Markdown with no required fields.
- Claude Code takes a project CLAUDE.md in either ./CLAUDE.md or ./.claude/CLAUDE.md.
- Codex checks each directory for AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames, and includes at most one file per directory.
- Cursor keeps project rules in .cursor/rules as .mdc files and also reads CLAUDE.md the same way it reads AGENTS.md.
- GitHub Copilot takes repository-wide instructions from a copilot-instructions.md file in the .github directory. It also accepts AGENTS.md files stored anywhere within the repository, or a single CLAUDE.md or GEMINI.md at the root.
The AGENTS.md site lists Codex from OpenAI among compatible agents, along with Cursor and the coding agent from GitHub Copilot.
How do I keep one source of truth?
Make AGENTS.md the only file you edit, and make every other file a pointer to it.
- Create an AGENTS.md file at the root of the repository and write the shared instructions there.
- Decide whether Claude Code needs a CLAUDE.md at all. Its docs say to add the import when your project also has a CLAUDE.md, when Project instructions is set to claude-md, or in sessions that cannot load AGENTS.md. Sessions on a Claude Code version before v2.1.277 read CLAUDE.md files only.
- Put any Claude-specific lines below the import. Claude reads the imported file first, then the rest, and keeping the import never makes Claude read AGENTS.md twice.
- Prefer the import over a symlink if anyone who clones the repository works on Windows, because creating a symlink there needs Administrator privileges or Developer Mode. If you need no Claude-specific lines, a symlink also works, but the Edit and Write tools refuse to write through a symlink.
- Add nothing for Cursor or Copilot. Cursor reads a project-root AGENTS.md written in plain markdown, and Copilot treats AGENTS.md as agent instructions used by AI agents.
- If your repository already uses another filename such as TEAM_GUIDE.md, add it to the fallback list for Codex.
- Avoid /import for ongoing sync. It appends a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md and carries over MCP servers, commands, subagents and skills.
Which file wins when instructions conflict?
Each doc states its own rule, and they are not identical.
- The AGENTS.md format says the closest AGENTS.md to the edited file wins, and explicit user chat prompts override everything.
- Codex concatenates files from the root down, and files closer to your current directory override earlier guidance because they appear later in the combined prompt. At global scope, in ~/.codex unless you set CODEX_HOME, Codex reads AGENTS.override.md if it exists and otherwise reads AGENTS.md.
- Copilot says the nearest AGENTS.md file in the directory tree takes precedence. Across clients, most surfaces combine applicable instruction files without defining a general precedence order.
- Copilot Chat on GitHub.com is the documented exception. All relevant instructions are provided, and personal instructions rank highest, then path-specific, repository-wide and agent instructions such as AGENTS.md, then organization instructions.
- Cursor's order is Team Rules, then Project Rules, then User Rules. Team rules come from Team and Enterprise plans, and two rules with the same filename in different folders both apply if their conditions match.
- Claude Code loads CLAUDE.md locations from broadest scope to most specific, so a project instruction appears in context after a user instruction.
Write the files so the order rarely matters. Copilot's docs say to avoid providing conflicting sets of instructions whenever possible.
What belongs in the shared file?
Put in what every agent needs on every task. The AGENTS.md site names project overview, build and test commands, code style guidelines, testing instructions and security considerations as popular sections.
Keep each line short and checkable. Claude's docs say to keep CLAUDE.md to facts Claude should hold in every session, such as build commands, conventions, project layout and "always do X" rules, and that more specific and concise instructions are followed more consistently. Copilot's docs favor short, self-contained statements. Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default, and says to raise the limit or split instructions across nested directories when you hit the cap.
Put scoped rules in each tool's own files. Claude's docs say to move an entry that only matters for one part of the codebase to a skill or a path-scoped rule. Cursor points to project rules in .cursor/rules/ for more control over when rules apply. Copilot uses NAME.instructions.md files below .github/instructions with an applyTo keyword in frontmatter, though on GitHub.com these are currently only supported for Copilot cloud agent and Copilot code review.
Do not treat the file as enforcement. Claude Code treats CLAUDE.md files and auto memory as context, not enforced configuration, and Copilot may not always follow your custom instructions the same way each time. For limits that must hold, Claude's debugging page says to use permissions or hooks.
How do I handle a monorepo?
Nest the files. The AGENTS.md site says to place another AGENTS.md inside each package, and agents read the nearest one. Codex docs describe overrides in nested directories for teams that need different rules, placed as close to specialized work as possible. In Cursor, nested AGENTS.md files are combined with parent directories, and more specific instructions take precedence.
Claude Code treats subdirectory CLAUDE.md files differently from the ones above the working directory. Files in subdirectories load on demand rather than at launch, and the debugging page says to load one by asking Claude to read another file in that subdirectory.
Handing work from one agent to the next is a separate problem, covered in coding agent handoffs. Pairing guides cover Claude Code with Codex and Cursor with Claude Code.
How do I check that each agent loaded the file?
Ask each tool to show what it loaded. In Claude Code, run /context all and check the list under Memory files. In Codex, the docs show the expected answer when you ask for loaded instruction sources: in their example, the global file first, the repository root AGENTS.md second, and the payments override last.
In Copilot Chat, expand the list of references at the top of a chat response and look for .github/copilot-instructions.md. For Copilot code review, edits to the files can be tested in the same pull request, because Copilot reads instructions from the head branch, not the base branch.
What else do readers ask?
Why does Cursor ignore my Markdown file in .cursor/rules?
Project rules must use the .mdc extension, and a plain .md file there is ignored because it has no frontmatter for description, globs and alwaysApply. For plain Markdown, use AGENTS.md.
Does CLAUDE.md in Cursor respect alwaysApply?
No. Cursor says CLAUDE.md files are always applied to every conversation, regardless of any alwaysApply setting.
Can I move existing Cursor or Copilot rules into Claude Code?
Yes. Running /init in Claude Code reads other tools' instruction files, including Cursor rules in .cursor/rules/ and Copilot rules in .github/copilot-instructions.md, and folds the relevant parts into a generated CLAUDE.md.
Who maintains the AGENTS.md format?
AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation.