Should you use AGENTS.md or Cursor rules?
Use AGENTS.md for instructions every coding agent should follow, and Cursor rules only for things that need Cursor-specific control, like file patterns. AGENTS.md is one plain Markdown file that Cursor, Codex, GitHub Copilot's coding agent, Gemini CLI and many others read. Cursor rules are .mdc files in .cursor/rules/ that only Cursor reads, but they can attach to matching files, load when relevant, or wait for an @-mention.
They aren't rivals inside Cursor. Cursor's rules documentation lists AGENTS.md as one of its own four kinds of rules, next to project rules, user rules and team rules. The choice is about which instructions go where.
What is AGENTS.md?
AGENTS.md is an open format for project instructions aimed at coding agents. The agents.md site calls it "A simple, open format for guiding coding agents" and describes it as "a README for agents": the build steps, test commands and conventions an agent needs, which would clutter a README written for people.
It has no required fields. In the site's words, "AGENTS.md is just standard Markdown." You can put one at the repo root and more in subfolders; agents read the nearest file in the directory tree, so "the closest one takes precedence," and "explicit user chat prompts override everything." The format is now stewarded by the Agentic AI Foundation under the Linux Foundation.
Support is broad. The site lists Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Jules, Windsurf, Zed, Warp, VS Code, Aider, goose, opencode, Devin, Junie and others. Codex's AGENTS.md docs say "Codex reads AGENTS.md files before doing any work." Claude Code's memory docs say it reads AGENTS.md as your project instructions when you have no CLAUDE.md. See the AGENTS.md guide for a template.
What are Cursor rules?
Cursor rules are Cursor's own instruction system. Project rules live in .cursor/rules/ as .mdc files, and the extension matters: Cursor's docs say "Project rules must use the .mdc extension," and a plain .md file there is ignored. Each file opens with frontmatter that sets when the rule applies:
| Rule type | Frontmatter | When it applies |
|---|---|---|
| Always Apply | alwaysApply: true |
Every chat session |
| Apply Intelligently | description |
When the agent decides it's relevant from the description |
| Apply to Specific Files | globs |
When a file matches the pattern |
| Apply Manually | none of the above | When you @-mention it, like @my-rule |
Cursor also has user rules, global preferences you set under Customize, Rules that apply across all projects, and team rules, managed from the dashboard on Team and Enterprise plans. The docs give the order as "Team Rules → Project Rules → User Rules," with earlier sources winning when guidance conflicts. Our Cursor rules guide covers the format in depth.
AGENTS.md vs Cursor rules side by side
| AGENTS.md | Cursor project rules | |
|---|---|---|
| File | AGENTS.md at the root and in any subfolder |
.cursor/rules/*.mdc, in subfolders if you like |
| Format | Plain Markdown, no metadata | Markdown with description, globs, alwaysApply frontmatter |
| Read by | Cursor plus Codex, Copilot's coding agent, Gemini CLI and many more | Cursor only |
| When it loads | Whenever the agent works in that directory tree | Always, by description, by file pattern, or on @-mention |
| Scoping | By folder: nearest file wins | By glob, description or manual mention |
| Number of files | Usually one per folder | As many small rules as you want |
| Setup | Create one file | One file per rule, with the right extension and frontmatter |
| Tooling | Any editor | /create-rule in Cursor's Agent, or Customize, Rules |
| Governed by | An open format under the Linux Foundation | Cursor |
| Best for | Project facts and conventions every agent needs | Cursor-specific, file-targeted or on-demand guidance |
When should you use AGENTS.md?
Pick AGENTS.md when the instructions are true no matter which agent reads them:
- Setup and commands: how to install, build, test and lint.
- Project layout: where the app, API, shared packages and generated files live.
- Conventions: naming, error handling, commit format, what never to edit.
- Teams with mixed tools. If one person uses Cursor, another Codex and a third Claude Code, a single AGENTS.md keeps them aligned without three copies.
- Monorepos. Put a short AGENTS.md in each package. Cursor combines nested files with their parents, and the more specific instructions take precedence.
Keep it lean, because it's read on every task. Codex, for example, stops adding instruction files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default.
When should you use Cursor rules?
Pick a Cursor rule when you need control AGENTS.md can't express:
- File-pattern rules. A React rule that attaches only when a
src/components/**/*.tsxfile is involved, or a SQL rule for migration files. AGENTS.md has no globs. - Rules the agent loads only when relevant. An Apply Intelligently rule costs nothing until its description matches, which helps for long, specialized guidance.
- Rules you call on demand. Apply Manually rules wait for an @-mention, which suits checklists you use now and then.
- Personal preferences. User rules follow you across every project without touching the repo.
- Organization standards. Team rules come from the dashboard and take precedence over project and user rules.
Cursor's advice for writing them applies to AGENTS.md too: "Keep rules under 500 lines," split large rules into smaller ones, and reference files instead of copying them in.
How do you split instructions between the two?
A clean split puts facts in AGENTS.md and Cursor-only behavior in .mdc files:
AGENTS.md setup, commands, layout, conventions
packages/api/AGENTS.md API-specific commands and rules
.cursor/rules/react.mdc globs: src/components/**/*.tsx
.cursor/rules/migrations.mdc description: writing database migrations
A file-pattern rule looks like this:
---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports.
- Style with Tailwind classes. Do not add new CSS files.
Don't repeat AGENTS.md content inside an always-on rule. Cursor reads both, so duplicates only cost context and drift apart over time.
What about Claude Code and Codex?
They read AGENTS.md, and neither one's docs say it loads .mdc rules as live instructions. The one exception is migration: Claude Code's /init reads Cursor rules in .cursor/rules/ and works the relevant parts into the CLAUDE.md it generates. Codex walks from the project root down to your working directory, reading AGENTS.md files along the way, and supports an AGENTS.override.md file that it checks first in each directory. Claude Code reads AGENTS.md when you have no CLAUDE.md in your working directory or above it. If you also keep a CLAUDE.md, see CLAUDE.md vs AGENTS.md.
Claude Code has its own counterpart to glob rules: Markdown files in .claude/rules/ can be scoped to file paths with a paths field. That is Claude-specific, just as .mdc is Cursor-specific. For guidance that should travel between tools and load only when relevant, an Agent Skill is the portable option; Cursor loads skills from .agents/skills/ and .cursor/skills/ and, for compatibility, from .claude/skills/ and .codex/skills/. See Cursor skills.
Which should you pick?
- Only Cursor, small project: AGENTS.md alone is often enough.
- Only Cursor, rules for specific file types: AGENTS.md plus a few
.mdcrules with globs. - Several agents on one repo: AGENTS.md as the shared source,
.mdcrules only for Cursor-specific needs. - Monorepo: a root AGENTS.md plus one per package.
- Preferences that are yours, not the project's: Cursor user rules.
- Company-wide standards in Cursor: team rules.
Where Kipt fits
Rules and AGENTS.md belong in each repo. The reusable pieces around them, prompts and Agent Skills, can live in one library. Kipt keeps those as Markdown in a private GitHub repo you own, and installs every skill into Claude Code or Codex with one command: npx skills add https://github.com/<you>/<repo>.git --all -g. To turn a rule you keep reusing into a skill, try the free SKILL.md generator.