Teams that run several AI coding agents in the same repository often end up with several instruction files: AGENTS.md for Codex, CLAUDE.md for Claude Code, Cursor rules, and frequently a GEMINI.md as well. The open standard for this job is AGENTS.md. According to the agents.md site, more than 60,000 open-source projects use it. This guide compares, from the vendors’ own documentation, which file each agent actually reads, where the formats overlap, and how to set up one shared guide so the tools do not contradict each other.
What AGENTS.md is
AGENTS.md is ordinary Markdown with no required fields. The official description is a README for agents. A human README still covers the quick start and contribution rules. AGENTS.md is where you put build and test commands, conventions, testing notes and security rules: the context a coding agent needs on every task, and which would only clutter a README.
OpenAI released the format in August 2025. Since the Agentic AI Foundation was formed on December 9, 2025, it has been stewarded under the Linux Foundation, alongside the Model Context Protocol and the goose agent framework. That is set out in the Linux Foundation announcement. The file is deliberately plain: any headings you like, plain text, and nested files in subprojects. According to agents.md, when instructions conflict the closest file wins, and an explicit prompt in the chat overrides everything.
Which file each agent reads
The table below is drawn from the documentation for Codex, Claude Code, Cursor and Gemini CLI, as of November 21, 2026. It is not a hands-on test. Where a vendor’s docs do not mention a format, the table says so.
| File | Codex | Claude Code | Cursor | Gemini CLI |
|---|---|---|---|---|
AGENTS.md |
Yes, plus AGENTS.override.md |
From v2.1.277, by default only when there is no CLAUDE.md |
Yes, at the project root and in subdirectories | Only if configured |
CLAUDE.md |
Only as a fallback, if configured and that directory has no AGENTS.md |
Yes, its native file | Yes, applied to every conversation | Only if configured |
.cursor/rules/*.mdc |
Not mentioned in the docs | Not mentioned in the docs | Yes, with four application modes | Not mentioned in the docs |
GEMINI.md |
Only as a fallback, if configured | Not mentioned in the docs | Not mentioned in the docs | Yes, the default file |
.claude/rules/ |
Not mentioned in the docs | Yes, including path-scoped rules | Not mentioned in the docs | Not mentioned in the docs |
The differences show up in the edge cases. If you maintain only one of these files, it is easy to assume every agent has seen it. As soon as two files sit side by side, each tool may be reading a different set.
The catch with Claude Code
Claude Code can read AGENTS.md directly from version 2.1.277. The documentation on project instructions is explicit about the default: if a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above it, Claude’s default setting claude-md-or-agents-md loads only the Claude files and skips AGENTS.md. A personal CLAUDE.local.md, meant to hold uncommitted local notes, is already enough to trigger that skip.
The same documentation offers three practical ways out:
- Do not add a project-level
CLAUDE.mdif AGENTS.md should be the only source. Your personal~/.claude/CLAUDE.mdand files under.claude/rules/do not count in that check and still load alongside AGENTS.md. - Add a thin
CLAUDE.mdwhose only content is the import@AGENTS.md. Claude then pulls in the shared file through the import and will not read it twice, whichever setting you use. - In
/config, set Project instructions toclaude-md-and-agents-mdif you want Claude to read both files, one after the other.
Anthropic warns that if two instructions contradict each other, Claude may pick one arbitrarily. Claude-specific rules therefore belong in .claude/rules/, not in the shared AGENTS.md. In some sessions, for example before v2.1.277 or when the built-in plugin is disabled, Claude does not read AGENTS.md directly at all. Importing it from a CLAUDE.md remains the robust path in those cases.
Cursor rules and CLAUDE.md
Cursor treats AGENTS.md as a simple alternative to project rules. According to the Cursor docs on rules, the files live at the project root and in subdirectories. Instructions are combined with those from parent directories, and the more specific file takes precedence.
Structured project rules in .cursor/rules/ remain the way to cover cases AGENTS.md cannot. They are Markdown files with the .mdc extension and YAML frontmatter. Cursor ignores a plain .md file in that folder. There are four modes: always apply, apply intelligently based on a description, apply when file paths match, or apply only when you mention the rule in chat. The docs also state that these rules do not affect Cursor Tab or other AI features outside Agent chat.
The Cursor help page on rules adds two points that mixed teams often miss. First, Cursor reads CLAUDE.md the same way it reads AGENTS.md and always applies it to every conversation, regardless of any alwaysApply frontmatter. A detailed CLAUDE.md written only for Claude Code therefore also reaches Cursor. Second, a .cursorrules file in the project root is legacy and is meant to be replaced by an Always Apply rule in .cursor/rules/.
Team Rules are available on Cursor’s Team and Enterprise plans and, when guidance conflicts, take precedence over project and user rules. Tool-specific, path-scoped guidance therefore belongs in .cursor/rules/, and shared conventions belong in AGENTS.md.
Gemini CLI and GEMINI.md
Gemini CLI loads GEMINI.md by default: globally from ~/.gemini/GEMINI.md, then from the workspace and its parent directories, and just in time when a tool touches a directory. The Gemini CLI documentation on context files shows how to change the filename in settings.json, for example:
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}
Without that entry, the CLI will not see an existing AGENTS.md. If you want to keep Gemini-specific notes, leave GEMINI.md in the list and put there only what the other agents do not need.
How to set up one shared guide
The docs above point to a setup that holds up in mixed teams:
- Put shared conventions, build and test commands, and security rules in an
AGENTS.mdat the repository root. In a monorepo, add a closer file in each package that needs its own guidance. - Codex reads that file on its own, including nested files and an optional
AGENTS.override.md. The Codex guide to AGENTS.md describes discovery: first the global files under~/.codex, then from the project root down to the current directory, with later files in the combined text overriding earlier ones. The chain stops at 32 KiB by default. - For Claude Code, place a thin
CLAUDE.mdnext to each AGENTS.md, containing only the line@AGENTS.md. That also works in sessions that cannot load AGENTS.md directly, and it stops an extraCLAUDE.local.mdfrom displacing the shared file, unless you deliberately want both files loaded. - Cursor reads AGENTS.md natively. Keep Claude-specific text out of
CLAUDE.md, because Cursor always applies that file as well. Put glob-scoped Cursor rules in.cursor/rules/. - In Gemini CLI, add
AGENTS.mdtocontext.fileNameif the team uses the CLI.
This pattern keeps the shared source separate from tool-specific extensions. Even when people also use graphical surfaces on top of terminal agents, the instruction file in the repository remains the stable layer, whatever surface someone has open. We compared three of those surfaces in Orca vs Monocode vs T3 Code. Which execution environment shapes the success rate more than the model is the subject of our comparison of coding agent harnesses. Claude-specific extensions beyond the instruction file are covered in the article on Claude Code Mods.
What belongs in the file
agents.md suggests a project overview, build and test commands, style guidelines, testing notes and security considerations as typical sections. Commit or pull request rules, known pitfalls and notes about large datasets belong there too: anything you would also tell a new teammate. Treat the file as living documentation, not a policy written once.
Three points from the vendor docs make good writing rules:
- Keep it short and specific. Claude Code stresses that concise, specific instructions are followed more consistently than long essays. Codex caps the loaded text at 32 KiB by default; oversized files are truncated or should be split across nested directories.
- Put mechanical checks in CI, not in the agent file. Codex recommends leaving formatting and lint checks in the pipeline and using AGENTS.md for the judgments a reviewer would otherwise have to explain again and again.
- Avoid contradictions. If a repository has an AGENTS.md and a detailed
CLAUDE.mdwith a different test command, Claude follows one, Codex follows the other, and Cursor may see both texts at once.
A compact skeleton can look like this:
# AGENTS.md
## Overview
- App in `apps/web`, API in `apps/api`.
## Build and tests
- Dependencies: `pnpm install`
- Tests: `pnpm test`
- Lint: `pnpm lint`
## Conventions
- New code in TypeScript; follow the existing patterns in the directory.
- Document public functions when behavior changes.
## Security
- Do not commit secrets.
- Do not add production dependencies without asking.
AGENTS.md does not replace a human README, CI or code review. It gives agents a shared, predictable place for what they need to know on every task. If you maintain that shared file and keep tool-specific rules in their native folders, you do not have to repeat the same conventions in three formats.




