Migrate .cursor/rules to AGENTS.md (Claude Code & Codex)

Make AGENTS.md the shared source of truth. Cursor's own rules docs treat AGENTS.md as a simple alternative to .cursor/rules, and read it in the project root and subdirectories. Codex reads AGENTS.md natively. Claude Code reads AGENTS.md when no CLAUDE.md exists (v2.1.277+), or you can keep a one-line CLAUDE.md with @AGENTS.md. Merge always-on .mdc bodies into root AGENTS.md; turn glob-scoped rules into nested AGENTS.md files by directory (AGENTS.md has no globs / alwaysApply). Paste your rules into the homepage converter to get copy-ready files.

Last updated October 14, 2026 · Sources checked October 14, 2026

Key facts

Cursor project rules	`.cursor/rules/*.mdc` with YAML frontmatter (`description`, `globs`, `alwaysApply`) — plain `.md` there is ignored
Cursor AGENTS.md	Plain markdown alternative; supported in the project root and nested subdirectories
Cursor .cursorrules	Legacy root file; Cursor help says it will be deprecated — migrate to a Project Rule set to Always Apply
Codex	Reads `AGENTS.md` (and `AGENTS.override.md`) from Codex home and each directory down to cwd
Claude Code	Prefers `CLAUDE.md`; loads `AGENTS.md` when no project `CLAUDE.md`/`CLAUDE.local.md` exists (v2.1.277+), or via `@AGENTS.md` import
What doesn't map	MDC `globs`, `alwaysApply`, and intelligent/manual rule types have no AGENTS.md equivalent — scope by directory instead
Fast path	Free converter on the homepage — paste `.mdc` / `.cursorrules`, get `AGENTS.md` + optional Claude/Cursor stubs

Why leave Cursor-only rules

If your team only uses Cursor, keep .cursor/rules/*.mdc — path-scoped rules and Team Rules are Cursor features. The pain starts when a second agent joins: Claude Code and Codex do not read .mdc frontmatter. Cursor's docs already point at AGENTS.md as the portable, plain-markdown alternative. One shared file stops you from maintaining three near-copies that drift.

Cursor's help center is explicit that the root .cursorrules file is legacy and will be deprecated: create a Project Rule, set it to Always Apply, then delete .cursorrules. That fixes Cursor alone. To also feed Claude Code and Codex, put the same text in AGENTS.md (Cursor reads that too).

What maps and what doesn't

Cursor format	AGENTS.md / other agents	Notes
`alwaysApply: true` body	Root `AGENTS.md` section	Copy the markdown body; drop the frontmatter
`globs:` path-scoped rule	Nested `AGENTS.md` in that directory	AGENTS.md has no glob field; closest-directory wins in Cursor and Codex
Intelligent / manual-only rule	Usually skip, or fold into a short always-on note	Other agents always load the whole file — no “apply when relevant”
`@file` mentions in an MDC body	Keep as plain path references, or use Claude's `@path` import inside `CLAUDE.md`	Cursor's rule `@file` is not inlined; Claude's `@path` in CLAUDE.md is expanded at launch
Root `.cursorrules`	Same body → `AGENTS.md` (and/or one Always Apply `.mdc`)	Per Cursor help: legacy; migrate then delete
Team Rules (dashboard)	Not portable	Stay in Cursor; copy any must-share lines into `AGENTS.md` by hand

Cross-cutting globs like **/*.test.ts that span many folders have no clean AGENTS.md equivalent. Either make them always-on (costs context everywhere) or duplicate a short nested file in each relevant directory. That trade-off is why teams keep a few Cursor-only .mdc files for true glob scopes and put the shared baseline in AGENTS.md.

Step-by-step migration

Inventory. List every file under .cursor/rules/ and any root .cursorrules. Note each rule's type: Always Apply, globs, intelligent, or manual.
Build root AGENTS.md. Concatenate the bodies of every alwaysApply: true rule (and .cursorrules) into one markdown file at the repo root. Drop YAML frontmatter. Keep it short — Claude Code's memory docs recommend under ~200 lines per instruction file.
Nest for globs. For each path-scoped rule, create AGENTS.md inside the directory that best matches the glob (for example src/api/AGENTS.md). Cursor combines nested AGENTS.md with parents; Codex walks from the project root down to cwd and concatenates.
Bridge Claude Code. Prefer a one-line CLAUDE.md containing @AGENTS.md, plus any Claude-only notes below it. Or rely on Claude Code's fallback (no project CLAUDE.md → read AGENTS.md) on v2.1.277+. A symlink ln -s AGENTS.md CLAUDE.md also works on Unix; on Windows prefer the @AGENTS.md import.
Codex. Nothing extra: commit root AGENTS.md. Optional nested AGENTS.override.md wins over AGENTS.md in the same directory.
Keep Cursor-only rules. Leave glob-heavy or Cursor-UI-only rules in .cursor/rules/. Delete duplicates that now live entirely in AGENTS.md so you don't maintain two copies.
Verify. In Cursor, confirm Agent still sees the shared instructions. In Claude Code run /memory or /context and check Memory files. In Codex ask it to summarize the current instructions.

Shortcut: paste an .mdc or .cursorrules file into the config converter on the homepage (source auto-detects Cursor MDC / .cursorrules) and copy the generated AGENTS.md, optional CLAUDE.md import, and Cursor stub.

Claude Code: import vs fallback vs /import

Per Claude Code's memory docs (checked 2026-10-14):

Default: if the project has a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md on the path, Claude reads those and not AGENTS.md — unless you set Project instructions to claude-md-and-agents-md in /config.
Fallback: with no project CLAUDE.md, Claude loads every AGENTS.md / .claude/AGENTS.md on the path (v2.1.277+).
Import: a CLAUDE.md containing @AGENTS.md always pulls AGENTS.md in, and is the safest bridge when some sessions can't load AGENTS.md directly.
One-shot migrate: /import (v2.1.213+) can bring Cursor rules from .cursor/rules/ or .cursorrules into Claude Code; /init can also fold Cursor rules into a generated CLAUDE.md. Treat imports as a checklist and audit what they missed.

After you migrate

Point teammates at the one AGENTS.md for every agent guide for per-agent caveats (Gemini CLI context.fileName, Zed .rules, Aider --read). Use the AGENTS.md linter before you commit. Skills and MCP are separate from instruction files — see the config matrix and the homepage converter's MCP tab if you are also moving servers between Cursor, Claude Code and Codex.

Sources

FAQ

Does Cursor read AGENTS.md?

Yes. Cursor's rules docs describe AGENTS.md as a simple markdown alternative to .cursor/rules, supported in the project root and in subdirectories. Nested AGENTS.md files combine with parents, with more specific instructions taking precedence.

Is .cursorrules still supported?

Cursor's help center says the root .cursorrules file is legacy and will be deprecated. Migrate by creating a Project Rule, setting it to Always Apply, then deleting .cursorrules. For multi-agent teams, put the same content in AGENTS.md.

Does Claude Code read AGENTS.md?

Yes, with conditions. By default Claude Code reads AGENTS.md when there is no project CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md on the path (v2.1.277+). If a CLAUDE.md exists, add @AGENTS.md as an import, or set Project instructions to claude-md-and-agents-md.

Does Codex read .cursor/rules?

No. Codex discovers AGENTS.override.md then AGENTS.md (plus optional fallback filenames you configure). Convert Cursor rules into AGENTS.md for Codex.

What happens to globs and alwaysApply?

They have no equivalent in AGENTS.md. Always-on bodies go into the root file; path-scoped rules become nested AGENTS.md files in the matching directory. Cross-cutting globs either become always-on or get duplicated per folder.

Can I convert without hand-editing?

Yes. Paste .mdc or .cursorrules into the free converter on getaicodingagent.com (homepage). It emits AGENTS.md and optional Claude Code / Cursor stubs in the browser — nothing is uploaded.

Migrate Cursor rules to AGENTS.md for Claude Code and Codex