AGENTS.md: One File to Share Rules Across Cursor, Claude Code, and Codex

It's becoming increasingly common for developers to use Cursor, Claude Code, and Codex in the same repository. The division of labor is roughly clear: Cursor handles reading and writing inside the editor, Claude Code takes care of multi-file operations in the terminal, and Codex runs background tasks while doubling as a second reviewer.

The problem lies in the rules. Each of the three tools reads a different instruction file, and three rule sets drift apart easily, ultimately causing agents to "fight" with each other.

Three Tools, Three Rule Sets

Every AI coding tool has its own configuration file convention. Cursor has its own rules folder, Claude Code reads claude.md, and Codex reads agents.md.

Used in isolation, none of this is a problem. But when all three tools work in the same repository, the three rule files gradually diverge—you add a coding standard to Cursor's rules, forget to sync it to claude.md, and Codex can't see it at all. The result is three agents in the same repository following three different codes of conduct.

This fragmentation isn't a minor annoyance. When agents disagree on code style, directory structure, or operational boundaries, their suggestions and modifications contradict each other, and developers end up spending more effort coordinating conflicts between tools.

AGENTS.md Is Already the de Facto Standard

The solution to this problem already exists. According to OpenAI's disclosure when it donated agents.md to the Linux Foundation in December 2025, more than 60,000 projects are already using this format. Along with Anthropic's MCP, it has become an open standard project under the Linux Foundation.

Codex natively supports agents.md. Its lookup logic starts from the repository root and searches downward level by level, with the file closest to the current folder taking the highest priority. This hierarchical lookup approach means you can place a general rule set at the root and more specific override rules in particular subdirectories.

Cursor also supports reading agents.md, treating it as a pure Markdown alternative to the rules folder.

When three rule files converge into one, the behavioral differences between agents naturally shrink.

The Linux Foundation and Open Standard Governance

The Linux Foundation is the world's largest open-source nonprofit, hosting a large number of critical infrastructure projects such as the Linux kernel, Kubernetes, and Node.js. It is often used as a neutral steward: when a technical format is adopted by multiple competing companies, donating it to the Foundation prevents a single vendor from controlling the direction of the standard. OpenAI's donation of agents.md to the Foundation means this format no longer belongs to any one AI vendor but is maintained jointly by the community, so other tools (including competitors like Anthropic and Google) can adopt it without fear of being locked out. Anthropic's MCP (Model Context Protocol) follows the same path—first proposed by one company, then neutralized through the Foundation to become a cross-vendor universal interface. Understanding this explains why agents.md has the potential to become a genuinely stable long-term de facto standard rather than just one company's private convention.

Hierarchical Configuration Lookup

Hierarchical lookup is a common configuration resolution pattern: a program starts from the current working directory and searches upward (or downward from the root) level by level, with files closer to the current context taking higher priority. Git's .gitignore, ESLint's .eslintrc, and npm's .npmrc all use similar mechanisms. For agents, this design lets you write a broad general rule set at the repository root and then write finer override rules in subdirectories like backend/ or frontend/, so that different modules follow their own specifications without piling all the rules into one giant file. This is also why agents.md can fit both large multi-package repositories and lightweight single-directory projects.

A Gotcha in Claude Code

Claude Code's support for agents.md has one thing worth particular attention.

If there is no claude.md in the repository, Claude Code reads agents.md. But if both files exist at the same time, it only reads claude.md and completely ignores agents.md.

This means developers migrating from other tools can run into the problem of rules not taking effect if an old claude.md is still sitting in the repository. The fix takes just one line: write a reference to agents.md in claude.md (such as @agents.md), and Claude Code will then load both files.

The File Reference Syntax @agents.md

Claude Code supports referencing other files in claude.md using the form @path, and the referenced content is inlined and expanded at load time—equivalent to writing the contents of that file directly into claude.md. This syntax applies not only to agents.md but can also be used to split up large instruction files—for example, breaking claude.md into multiple fragments like @rules/style.md and @rules/testing.md, making it easier for teams to divide maintenance work and review versions. The advantage of using references instead of copy-paste is that agents.md remains the single source of truth: what Cursor and Codex read is always identical to what Claude Code reads, with no risk of drift from manual syncing. Note that reference paths are usually resolved relative to the location of claude.md, so when referencing across directories you should write out the relative path clearly.

How to Write an Effective AGENTS.md

Keep the file short and practical. The effective content the developer community has summarized includes:

• Build and test commands: Let the agent know how to compile, run, and verify the code
• Code conventions: Naming rules, formatting preferences, import order, etc.
• Directories not to touch: Clearly specify which folders the agent should not modify

One technical limitation to keep in mind: Codex's default limit for reading agents.md is 32KB. Anything beyond that size gets truncated.

More importantly, understand the positioning of agents.md—it is guidance, not enforcement. The agent may or may not follow it. For rules that must be strictly enforced, you should use hardcoding or hooks.

Hooks and Hard Constraints

Hooks are scripts that automatically trigger at key points in an agent's workflow (such as before a commit, after a file save, or before and after tool calls). The essential difference between them and prompt-style instructions like agents.md lies in the execution layer: prompts are natural-language suggestions to the model, which the model may ignore due to context length, misunderstanding, or conflicting priorities; hooks are deterministic program logic that executes unconditionally once triggered, and operations that violate the rules are directly rejected or rolled back. Therefore, any non-negotiable constraints—such as prohibiting the commit of secrets, prohibiting changes to the migrations/ directory, or requiring lint to pass before committing—should be backed by hooks, pre-commit hooks, or CI checks, while soft suggestions like style preferences and naming habits can be left to agents.md. Understanding this dividing line between "suggestion vs. enforcement" is the key to designing reliable agent collaboration workflows.

What the 32KB Limit Means

32KB is roughly equivalent to 8,000 to 10,000 English words, or about 15,000 to 20,000 Chinese characters. For an instruction file this capacity is actually quite generous, but a large monolithic repository that tries to cram the rules of every module into one file can easily hit the ceiling. The portion over the limit is silently truncated—meaning rules at the end of the file quietly stop working, with no error. This is more dangerous than a direct failure. The way to avoid it is exactly the hierarchical lookup mentioned earlier: put general rules at the root and push module-specific rules down into subdirectories, which both controls individual file size and ensures rules take effect close to where they apply.

Let a Second Agent Do the Review

A practice worth trying is having a second agent review the first agent's work. Developer feedback is that this approach catches issues the first agent missed.

For example, after letting Codex finish a task in the background, have Claude Code or Cursor check the modifications. Different tools have different models and context windows, and their review perspectives differ too—this diversity itself is a form of quality assurance.

One file, three tools, one set of rules. In an era when multi-agent collaboration has become routine, using agents.md to unify the rules entry point is the most direct way to reduce coordination costs.

Why Heterogeneous Model Review Is More Effective

Models from different vendors differ in training data, alignment strategies, and decoding methods, which leads to differences in how they "attend" to the same piece of code: one model may be especially sensitive to security boundaries, while another may be better at spotting type or concurrency issues. When the reviewer and the reviewed use the same model and the same context, they tend to share the same blind spots, and errors are easily masked by "consistency." Switching to a model from another vendor as the second reviewer is like introducing an independent perspective and can significantly increase the defect discovery rate. This aligns with the traditional code review principle of "a fresh pair of eyes," and is also akin to the software engineering approach of cross-scanning with multiple static analysis tools. Differences in context windows matter too: a model with a larger window can see more related files at once, thereby uncovering cross-file dependency issues.

One-line Summary

Use AGENTS.md to unify the rules entry point for Cursor, Claude Code, and Codex—and have a second agent do the review.

Paragraph Summary

Using Cursor, Claude Code, and Codex in the same repository has become the norm, but three separate rule files drift easily, causing behavioral conflicts between agents. The solution is to converge on AGENTS.md: this format was donated by OpenAI to the Linux Foundation, has been adopted by more than 60,000 projects, is natively supported by Codex with directory-hierarchical lookup, and is also used by Cursor as an alternative to rules. Claude Code has a gotcha: when claude.md and agents.md both exist, it only reads the former, which needs to be fixed by referencing @agents.md in claude.md. An effective AGENTS.md should stay short, include build and test commands, code conventions, and directories not to modify, pay attention to Codex's default 32KB truncation limit, and make clear that it is guidance rather than enforcement. In addition, having a second agent review the first agent's work can capture missed issues by leveraging the differing perspectives of different models.