AGENTS.md vs CLAUDE.md vs .cursorrules: Which File Each AI Coding Tool Reads (2026)

AI coding agents no longer agree on a single file name, but they are converging. AGENTS.md is the cross-tool format, CLAUDE.md is still what Claude Code loads first, .cursor/rules/*.mdc is Cursor’s scoped rule system, and .cursorrules is legacy. This guide shows which tool reads which file today, then what 113 source-audited open-source repositories in the STACK IT FAST directory actually ship.

1. Which file each tool reads

Two consequences matter in practice:

• Claude Code ignores your AGENTS.md if a CLAUDE.md sits next to it. The fallback only applies to folders without a CLAUDE.md. Reports also note the fallback depends on Claude Code’s feature flags, so it may not apply on Bedrock, Vertex or with telemetry disabled.
• Cursor applies CLAUDE.md to everything. Anything Claude-specific you put there also reaches Cursor sessions, with no way to scope it.

2. What 113 open-source repos actually ship

We checked the root of every repository in the directory at the exact commit its deep dive was audited against.

AGENTS.md and CLAUDE.md usually travel together. 49 repos ship both, 13 ship only AGENTS.md (for example Astro, Temporal, Mattermost and Logto), and 12 ship only CLAUDE.md (for example Medusa, Hasura and OpenObserve). The 13 AGENTS.md-only repos are the ones whose instructions Claude Code started reading in September 2026.

In the 49 repos that ship both, maintainers solve the duplication three ways:

Projects using the pointer pattern include n8n, Sentry, Grafana, Gitea and Supabase Studio. Cal.com, Twenty and LibreChat keep a separate CLAUDE.md.

Cursor’s own scoped rules are much rarer: 15 repos ship a .cursor/rules/ directory, including PostHog, shadcn/ui, tRPC and Trigger.dev, and only 3 still carry a legacy .cursorrules.

3. The setup we recommend

1. Write AGENTS.md as the source of truth. Build commands, test commands, code style, directory map and non-negotiables. It is the one file every major agent reads.
2. Make CLAUDE.md a pointer. Start it with @AGENTS.md, then add only Claude-specific instructions (for example sub-agent or hook conventions). This keeps Claude Code on the same rules even though it prefers CLAUDE.md.
3. Use .cursor/rules/*.mdc only for scoped rules. Glob-attached rules (for example only for *.sql or apps/api/**) are where Cursor’s format adds something AGENTS.md cannot.
4. Delete .cursorrules. Move its content into an always-apply .mdc rule or into AGENTS.md.
5. Nest AGENTS.md in monorepos. A short AGENTS.md per package keeps instructions close to the code; Cursor and Codex apply the nearest file.

4. Migrating from .cursorrules

.cursorrules                      → delete
  project-wide conventions        → AGENTS.md
  rules for specific paths        → .cursor/rules/<name>.mdc  (globs: ["apps/api/**"])
CLAUDE.md (if you have one)       → first line: @AGENTS.md, keep Claude-only notes below

Vendors have started shipping skills too: TypeSafe publishes an official agent skill for its Jev model instead of an MCP server. Every stack rule set on STACK IT FAST already ships in all of these formats: an AGENTS.md, a CLAUDE.md, a Cursor .mdc rule and an installable Agent Skill (SKILL.md), derived from production repositories that use that stack.

5. Methodology

• Sample: the 113 open-source repositories with a published, source-audited deep dive in the STACK IT FAST directory.
• Snapshot: the repository root at the commit each deep dive was audited against (September 2026), read through the GitHub contents API. Nested instruction files inside subdirectories were not counted.
• Pointer detection: a CLAUDE.md of 64 bytes or less that names AGENTS.md (a git symlink or a one-line @AGENTS.md import) counts as a pointer.
• Tool behaviour: taken from Cursor’s rules documentation (August 2026), the Claude Code v2.1.277 release coverage (September 2026) and the agents.md compatibility list.