AGENTS.md vs CLAUDE.md vs Cursor Rules: What Each Agent Actually Reads

Documentation checked: Claude Code v2.1.277+ memory docs, Cursor Rules docs, and GitHub Copilot custom-instruction docs, reviewed September 27, 2026.

AGENTS.md, CLAUDE.md, and Cursor Rules all try to solve the same problem: giving an AI coding agent enough project context to make useful changes. The names look interchangeable, but the files are not read in exactly the same way by every tool.

This guide compares the three approaches, documents the current support rules from official sources, and proposes a controlled experiment for measuring adherence. The goal is not to declare one universal winner. It is to help a small team choose a file strategy that is portable, testable, and honest about its limits.

What these files are designed to do

An instruction file is persistent project context. It can tell an agent how to install dependencies, which test command to run, which directories to avoid, how code is structured, and what must be checked before a change is considered complete.

That context is useful because coding agents do not retain a perfect memory of every repository between model calls. Rules are inserted into the agent’s working context according to the product’s loading behavior. They guide the model; they do not replace permissions, sandboxing, CI checks, branch protection, or human review.

AGENTS.md: the portable baseline

The official AGENTS.md site describes the format as a README for coding agents. It is ordinary Markdown, so a repository can use headings such as project overview, setup commands, testing instructions, code style, security considerations, and pull-request rules.

The format is intentionally not a proprietary schema. That makes it easy to review in Git and easy to copy between tools. The official site also documents nested files for monorepos. A closer file can provide instructions for a subproject, but the exact precedence still belongs to the agent that loads it.

AGENTS.md is a good default when a team uses more than one coding agent. It avoids putting every tool-specific detail into the shared file, while still giving agents a predictable starting point.

CLAUDE.md: Claude Code’s project memory

Claude Code has its own instruction system built around CLAUDE.md. Anthropic’s documentation now describes direct AGENTS.md support as well, but the behavior is conditional.

With the default project-instructions setting, Claude Code reads AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. If a CLAUDE.md is present, CLAUDE.md takes precedence over AGENTS.md by default. A CLAUDE.md can also import AGENTS.md explicitly, or the project can change the setting to read both.

Direct AGENTS.md support requires Claude Code v2.1.277 or later. Before v2.1.281, some sessions, including certain Amazon Bedrock or telemetry-disabled sessions, may read only CLAUDE.md. In those cases, importing AGENTS.md from CLAUDE.md is a practical fallback.

This distinction matters. A team can add a CLAUDE.md for a local preference and unintentionally change which shared AGENTS.md instructions are loaded. Claude Code also documents a minimum version for direct AGENTS.md support, so articles should always state the tested version rather than treating support as timeless.

Cursor Rules: more control, more product coupling

Cursor supports project rules in .cursor/rules as .mdc files. These files can be always applied, attached to matching paths, selected intelligently from a description, or invoked manually. That makes Cursor Rules more expressive than a single plain Markdown file.

Cursor also documents AGENTS.md as a simpler alternative. A root or nested AGENTS.md can be easier for a team to share, while `.cursor/rules` is useful when the project needs scoped behavior such as separate frontend, backend, or test rules.

The trade-off is maintenance. A repository that uses both AGENTS.md and `.cursor/rules` must decide which instructions are portable and which are Cursor-specific. Duplicate rules can drift. Conflicting rules can also make a failed task difficult to diagnose.

Current support matrix

The table below is a documentation-based starting point, not a guarantee for every release channel. Check the product version before publishing an internal standard.

The controlled test: do agents actually follow the rules?

A file can be supported and still be ineffective. The useful question is not only “does the tool read this file?” It is “does the agent follow the instruction when the task creates pressure to do something else?”

Use a small repository or a disposable fixture. Write ten rules across six categories:

• Commands: use the documented install, build, and test commands.
• Style: follow the specified naming and formatting convention.
• Boundaries: do not edit a protected directory.
• Testing: add or update a test for changed behavior.
• Security: never print a secret or disable a security check.
• Workflow: summarize the validation performed before finishing.

Then run the same five tasks with the same repository state and record the result. Keep the model family, temperature or equivalent settings, tool permissions, and prompt as consistent as the products allow.

How to score rule adherence

Use a binary or three-level score for each rule. A simple scale is easier to audit than a subjective overall impression.

Report the individual rules, not only an average. An agent that scores well overall but edits a protected directory is not equivalent to an agent that misses a formatting preference.

rules = [
    "run pnpm test before finishing",
    "do not edit the migrations directory",
    "use the repository naming convention",
    "never print environment secrets",
]

for agent in agents:
    for task in tasks:
        result = run_same_task(agent, task, clean_repo=True)
        score = score_rule_adherence(result, rules)
        save_matrix(agent, task, score)

publish_per_rule_results()

This is an evaluation pattern, not a claim that every agent can be automated through the same API. If you cannot run all tools programmatically, use a documented manual protocol and preserve the transcripts, diffs, commands, and versions.

Why coding agents ignore rules

The file was never loaded

Check the product’s startup message, diagnostics, or documentation. A file in the wrong directory, a version without support, or a conflicting higher-priority file can make a valid rule invisible.

The instruction is vague

“Write clean code” is difficult to score. “Run pnpm test after changing application code and report the result” is observable. Prefer a command, boundary, condition, or expected artifact.

The rule conflicts with the task or another rule

Instruction files are not a complete authority hierarchy. User requests, system policies, tool permissions, and product-specific precedence can all matter. State the rule in a way that makes its scope clear, and avoid duplicating the same instruction in several places.

The context budget is crowded

Long files full of background prose compete with the task itself. Keep the shared file concise and move specialized details to scoped rules or linked documentation. A shorter rule that is easy to retrieve can be more effective than a large manual.

The rule asks for a check without enforcing it

If a test is important, enforce it in CI. If a path must not be changed, use permissions, code ownership, protected branches, or a validation script. Treat the instruction file as guidance and CI as the enforcement layer.

How to write rules that stick

1. Start with the repository’s real workflow. Include commands that have been tested, not commands copied from a template.
2. Use observable language. Say what the agent should run, edit, avoid, or report.
3. Put high-value rules first. Build, test, security, and boundaries matter more than generic style advice.
4. Keep instructions close to their scope. Use nested AGENTS.md files or Cursor path rules for subprojects.
5. Remove contradictions. One authoritative rule is better than three slightly different versions.
6. Review changes like code. Update the file in pull requests and test rule changes with representative tasks.

One file or several?

For a multi-agent repository, a practical pattern is:

• AGENTS.md: portable setup, tests, architecture, security boundaries, and contribution expectations.
• CLAUDE.md: Claude-specific imports, workflows, or local conventions that other tools do not understand.
• .cursor/rules: path-scoped or condition-based rules that need Cursor’s `.mdc` metadata.
• CI and permissions: checks that must not depend on model compliance.

Avoid copying the entire shared file into every tool-specific file. If you need both, make the relationship explicit and test which copy wins.

Migration example

Suppose a team has a long .cursorrules file. First extract the portable parts: setup commands, tests, architecture, naming, security, and boundaries. Move those into a root AGENTS.md. Keep only Cursor-specific path patterns and application metadata in .cursor/rules/*.mdc.

If the team uses Claude Code, do not assume that adding an empty CLAUDE.md is harmless. Under Claude Code’s default behavior, a CLAUDE.md in the project hierarchy can change whether AGENTS.md is loaded. Either keep the shared instructions in CLAUDE.md, explicitly import AGENTS.md, or configure Project instructions to read both.

Limits of the comparison

Adherence is not a permanent property of an agent. Results can change with the model, product version, context length, tool permissions, task wording, repository size, and rule placement. A five-task experiment can reveal useful failure modes, but it cannot prove that one tool always follows instructions better.

Publish the exact versions, prompts, repository fixture, rule file, task list, and scoring rubric. If a result is not reproducible, describe it as an observation rather than a universal benchmark.

Frequently asked questions

Is AGENTS.md replacing CLAUDE.md?

No. AGENTS.md is a portable option, while CLAUDE.md provides Claude Code-specific behavior and configuration. A repository may use both, but it must understand precedence and avoid conflicting instructions.

Does Cursor read .cursorrules?

Cursor’s current documentation emphasizes project rules in .cursor/rules using .mdc files, and documents AGENTS.md as a simpler alternative. Treat legacy .cursorrules behavior as something to verify in the version you use rather than the preferred new structure.

Can AGENTS.md enforce security?

No. It can tell an agent not to expose secrets or edit a protected path, but enforcement should come from secret management, permissions, sandboxing, CI, code ownership, and review.

Should I put every project detail in one file?

No. Put the instructions most agents need in the portable file, then use nested or tool-specific rules for details that depend on a directory or product.

How often should we test instruction adherence?

Run a small regression set after changing the instruction files, switching models, upgrading the agent, changing permissions, or changing the repository workflow.

Conclusion

AGENTS.md is a strong portable baseline, but “supported” does not mean “always loaded” or “always obeyed.” Claude Code, Cursor, and GitHub Copilot each expose different file choices and precedence rules. The reliable approach is to keep shared instructions concise, use product-specific features deliberately, test adherence on identical tasks, and enforce critical controls outside the model.

Editorial note: Instruction-file support changes quickly. Recheck the official documentation and the installed agent version before standardizing a workflow.

Sources and further reading

1. AGENTS.md official format — format, examples, supported-agent ecosystem, nested files, and guidance.
2. Claude Code memory and AGENTS.md — loading conditions, precedence, settings, and version limitations.
3. Cursor Rules documentation — `.cursor/rules`, `.mdc` files, scoped rules, and AGENTS.md support.
4. GitHub Copilot custom-instruction support — feature-by-feature support for AGENTS.md and other instruction files.
5. GitHub: How to write a great AGENTS.md — lessons from a large repository analysis.

Related PromptSphere reading: RAG Evaluation, AI Agent Tool-Call Auditing, AI Agent Observability, and LLM Model Routing.