AGENTS.md vs .cursorrules vs CLAUDE.md: What Reads What

Your project now has three candidate rule files sitting at the root — AGENTS.md, .cursorrules, and CLAUDE.md — and only one of them does anything for the tool you are actually running. Add a fourth "just in case" and you have created a maintenance problem instead of a convention: three places to update every time a decision changes, with nothing forcing them to agree.

AGENTS.md is a plain Markdown file at the project root that OpenAI's Codex CLI, and several other coding agents, load automatically before running a task. .cursorrules and its successor, the .cursor/rules/*.mdc format, are what Cursor reads instead. CLAUDE.md and the .claude/ directory are what Claude Code loads. None of the three formats read each other's file, so a rule written into .cursorrules is invisible to Claude Code, and a rule written into CLAUDE.md is invisible to Cursor.

Most repos end up with more than one of these files the same way: a developer adopts Cursor first, writes a .cursorrules file, then starts using Claude Code for a different part of the workflow and adds a CLAUDE.md without revisiting the first file. Six months later a third teammate adds Codex CLI and an AGENTS.md, and now three files describe three overlapping but not identical sets of conventions, written at three different points in the project's history.

What Is AGENTS.md, and Which Tools Read It?

AGENTS.md is a plain Markdown file at your project root that Codex CLI, and a growing list of compatible coding agents, load automatically before starting a task. It typically holds setup commands, test commands, and the conventions the agent should follow without being told each time in the prompt.

Because it is just Markdown with no required frontmatter, AGENTS.md is the simplest of the three files to write and the easiest to keep short. The tradeoff is that it has no scoping mechanism — everything in it applies to every request, all the time, so it should stay limited to facts that are true everywhere in the repo.

A typical AGENTS.md covers three things: how to install dependencies, how to run the test suite, and any conventions that would otherwise need repeating in every prompt — for example, "use pnpm, not npm" or "run the linter before you consider a task done." Because it has no scoping mechanism, everything in it applies to every request, all the time, so it should stay limited to facts that are true everywhere in the repo rather than growing into a full style guide.

What Does .cursorrules Actually Do in Cursor?

Cursor reads either a single .cursorrules file at the project root (the legacy format) or a .cursor/rules/ directory of .mdc files (the current format). Each .mdc file carries frontmatter fields — description, globs, and alwaysApply — that control when the rule loads, so a rule for your API routes does not clutter the context when you are editing a stylesheet.

Cursor injects matching rules into every relevant prompt's context automatically, so you never re-paste conventions by hand. Neither AGENTS.md nor CLAUDE.md do anything inside Cursor itself — Cursor only reads its own two formats.

How Is CLAUDE.md Different From a Skill File?

CLAUDE.md is a plain Markdown file that Claude Code reads on every run for durable project facts and standing instructions. A skill, defined in a SKILL.md file with frontmatter, works differently: Claude Code loads a skill only when its description matches the current request, keeping narrow expert instructions out of the context until they are actually needed.

That difference has a practical consequence. CLAUDE.md is always in context, so it should hold only the handful of facts that apply to virtually everything you ask Claude Code to do — repo layout, non-obvious constraints, standing rules — not a full style guide for every stack in a large repo. Stack-specific or task-specific instructions belong in a skill instead, where they only cost context when they are relevant.

File-by-File: What Each Convention Covers

The table below lines up the five formats you are likely to see in a repo that touches more than one AI coding tool.

Do These Files Ever Conflict With Each Other?

Not at the tool level. Cursor never opens CLAUDE.md, and Claude Code never opens .cursorrules, so there is no runtime conflict to resolve. The conflict happens at the human level: you update one file after a decision — say, switching a stack from Tailwind v3 to v4 — and forget the other two, so half your tools keep generating code against the old convention while the rest catch up.

That gap is invisible until it shows up as inconsistent output between two developers on the same team using different tools, or between two sessions of your own work months apart. Neither tool logs a warning when this happens, because from each tool's point of view it followed its own file correctly — the drift only exists when you compare the two outputs side by side.

Keeping Rules in Sync Across Tools

None of this requires picking a single "winning" tool. The fix is a short, repeatable process that treats the underlying conventions as the real asset and the files as three exports of it:

1. Pick one file as the source of truth for conventions that apply everywhere — stack versions, formatting, test commands.
2. Copy the shared content into each tool's file the moment you edit the source, not "when you remember."
3. Keep tool-specific behavior, like Cursor's glob-scoped .mdc rules or Claude Code's on-demand skills, in their own files instead of duplicating it everywhere.
4. Commit every rules file to the repo so a new contributor's tool picks up the same conventions on day one.
5. Re-check every rules file whenever a stack has a major version bump — that is when rules go stale fastest.

Doing this by hand, for every stack you touch, is exactly the maintenance problem a maintained rules pack exists to remove. BuyCoded's Cursor Rules Mega-Pack ships 1,057 rules across 20 stacks in both Cursor formats — legacy .cursorrules and current .mdc — already reissued when a stack's idioms shift, so tracking a Next.js or Tailwind default change by hand is not the part you have to own.

Is Maintaining Three Rules Files Worth It?

The obvious objection: writing your own rules is free, and copying a table like the one above costs nothing but time. That holds for a single stack on a solo project. It stops holding the moment you are juggling more than two stacks, more than one AI coding tool, or a team where everyone's local rules quietly diverge. There is also a migration-effort concern — dropping in someone else's rules means reading them first to make sure they match your actual stack versions, not just the stack's name. A maintained pack does not replace understanding what each file does — it replaces the ongoing work of rewriting and re-testing rules every time a stack ships a breaking change, which is the part that is genuinely tedious rather than genuinely hard.

Start With the Rules You Already Need

Whichever file your tools read, the fastest way to stop rules from drifting is to start from a set already tested against current stack versions instead of writing one from a blank file. Browse the full BuyCoded catalog, pick the pack that matches your stack, and drop the rules straight into your project's AGENTS.md, .cursorrules, or CLAUDE.md today.