Home / Compare / agents.md vs cursor rules

agents.md vs cursor rules — what goes where in 2026

Two markdown files that look similar, ship next to each other, and shape what your AI coding agent does. Here is how to choose between them, when to use both, and how to migrate.

The short version

• agents.md is the cross-tool spec for telling any agent what your repository expects. Codex CLI, Cursor, Aider, and Cline all read it (in priority orders that vary).
• .cursorrules is Cursor-specific. It loads only inside Cursor, and Cursor prefers it over agents.md when both exist.
• If you ship a public repo and want any agent to behave: agents.md. If you and your team are 100% on Cursor: .cursorrules. If both: write agents.md and let .cursorrules be a thin pointer.

What loads where

Where each one belongs

Pick by your audience.

Use agents.md when

• The repo is open-source. Contributors arrive with whatever tool they already use.
• You care about Codex CLI, Aider, or Cline reading the same instructions.
• The instructions are universal: code style, test commands, deployment workflow, branch naming. Things that aren't Cursor-feature-specific.

Use .cursorrules when

• Your team is fully on Cursor and the rules call out Cursor-specific UI ("when using @docs, prefer ...").
• You want to ship rules per workspace that other tools shouldn't see.
• You have legacy Cursor projects that already use .cursorrules and rewriting is overkill.

Migration: .cursorrules to agents.md

Most .cursorrules files port directly. The notable differences:

• Strip Cursor-specific syntax (@docs, @web, @codebase references) — replace with generic phrasing.
• Wrap in a clear top-level ## Agent instructions heading per the agents.md spec.
• Add a one-line ## Test command and ## Build command section. Codex CLI and Aider use these.
• Move tool-specific overrides to ## Cursor / ## Claude Code subheadings if you need them.

The reverse migration (agents.md → .cursorrules) is rarely worth doing.

Both at the same time

Yes, you can ship both. A common pattern in 2026:

repo-root/agents.md            # source of truth, ~200 lines
.cursorrules         # one line: "See agents.md."
CLAUDE.md            # one line: "See agents.md." + Claude Code-specific overrides

This way Cursor users get redirected to the canonical doc. Claude Code users get their own pointer. Codex/Aider/Cline users hit agents.md directly.

When neither is enough

If the agent is doing something repeatable — a multi-file refactor, a migration, a code review — neither file format helps. That's what skills and workflows are for. agents.md and .cursorrules describe how the agent should behave in general; skills describe specific procedures.

Browse MDs

• agents.md examples — production agents.md files from real repos
• Cursor rules — curated .cursorrules library
• agents.md vs CLAUDE.md →
• Cursor rules vs Claude skills →

Last updated: 2026-04-25.