AGENTS.md: One Rulebook for Cursor, Claude Code and Codex

If you use more than one AI coding tool on the same repository, you have probably met the problem: each tool wants its own instruction file. Cursor has its rules folder, Claude Code has CLAUDE.md, and Codex has AGENTS.md. Three files, written at different times, quietly drift apart, and then the agents start to disagree about how the project works.

This is what I found when I checked each tool's own documentation: how the three read instructions, the one gotcha in Claude Code, and a setup where they all follow the same rules.

What is AGENTS.md?

AGENTS.md is a plain markdown file at the root of a repository that tells AI coding agents how the project works. It is meant to be the README for agents: the commands to build and test, the conventions to follow, the places not to touch.

It is also an open standard. In December 2025 the Linux Foundation announced the Agentic AI Foundation, with Anthropic, Block and OpenAI as founding contributors. Three projects were contributed: Anthropic's Model Context Protocol, Block's goose, and OpenAI's AGENTS.md. The Linux Foundation's announcement says AGENTS.md has been adopted by more than 60,000 open source projects and agent frameworks. That is the foundation's own figure, so treat it as a claim from the organisers rather than an independent count.

How each tool reads it

Codex

Codex builds its instruction chain once per run. At the global level it reads AGENTS.override.md from its home directory if that exists, otherwise AGENTS.md. Then it starts at the project root, usually the Git root, and walks down to the directory you are working in. In each directory it takes at most one file, checking AGENTS.override.md first, then AGENTS.md, then any fallback names you have configured.

The files are joined from the root downwards, so the ones nearest your work come last and win. Codex stops adding files once the combined size reaches 32 KiB by default (project_doc_max_bytes), which is a good reason to keep the file short.

Cursor

Cursor supports AGENTS.md as a simple alternative to .cursor/rules. It is plain markdown with no frontmatter, so there is no metadata controlling when it applies. It works at the project root and in subdirectories: nested files combine with their parents, and the more specific instructions take precedence.

One detail from Cursor's documentation is easy to miss: plain .md files placed inside .cursor/rules are ignored. If you want plain markdown, AGENTS.md is the way to get it.

Claude Code

Claude Code is the careful one. Its documentation sets out exactly what it reads by default:

The first row is recent. Until September 2026 the documented workaround was to create a CLAUDE.md that imports AGENTS.md. On 18 September 2026 Claude Code team member Thariq Shihipar announced that, from version 2.1.277, Claude falls back to AGENTS.md when a folder has no CLAUDE.md.

The one-line fix

Import AGENTS.md from inside CLAUDE.md with Claude Code's @ import syntax:

@AGENTS.md
 
## Claude Code only
- Use plan mode before large changes.

Now AGENTS.md is the single source of truth. Claude Code loads it through the import, Codex reads it natively and Cursor reads it as its alternative to .cursor/rules. Anything that really is specific to one tool goes in that tool's own file underneath. This site's repository is set up the same way: its CLAUDE.md starts with @AGENTS.md.

What belongs in the file

Keep it short and practical. The things worth writing down:

• The exact commands to build, test and lint the project.
• Code conventions that are not obvious from the code.
• Folders and files the agent must not touch.
• Where the facts live, such as the folder that holds content or configuration.

Because Codex stops reading at 32 KiB by default, and because every extra line competes for the model's attention, a file that fits on a page works better than one that tries to say everything.

Guidance, not enforcement

An instruction file is context the model weighs, not enforced configuration. Claude Code's documentation says so directly: to block an action regardless of what the model decides, use a PreToolUse hook instead. The same split applies to the other tools. Put preferences and conventions in AGENTS.md, and put anything that must never happen into a mechanism the agent cannot talk its way past.

What the three tools are used for

People who run several tools on one repository describe a rough split: Cursor for reading and editing in the editor with inline diffs, Claude Code for multi-file work in the terminal, and Codex for background tasks, sometimes also as a second reviewer of another agent's work. These are practitioner reports from comparison articles rather than measurements, and the boundaries are blurring as each tool adds the others' features, so treat them as defaults, not rules. What does not change is the benefit of one shared rulebook: whichever agent wrote the code, it followed the same conventions.

Further reading

• Linux Foundation, announcement of the Agentic AI Foundation: the December 2025 formation and the three contributed projects.
• Claude Code documentation, How Claude remembers your project: the table of what Claude reads, the @ import and the hook advice.
• Cursor documentation, Rules: how AGENTS.md relates to .cursor/rules.
• Codex documentation, AGENTS.md: discovery order, overrides and the 32 KiB limit.
• Simon Willison, Claude Code now supports AGENTS.md: the 18 September 2026 announcement.
• My own article, What Is a Harness Engineer?, explains why the environment around the model matters more than any single prompt.