September 3, 2026 · Comparison · EN

AGENTS.md vs Cursor Rules: What Should Your Repository Use in 2026?

AGENTS.md and Cursor Project Rules are both version-controlled repository instructions in modern Cursor. Learn what each format does, when to combine them, and how to prepare a repo for local and Cloud Agents.

AGENTS.md vs Cursor Rules: What Should Your Repository Use in 2026?

AGENTS.md is a plain-Markdown repository contract, while Cursor Project Rules are version-controlled .mdc files with metadata that controls when each rule applies. In modern Cursor, both can travel with the repository; the real choice is portable simplicity versus Cursor-specific activation and scoping.

That distinction matters because older comparisons often describe Cursor Rules as local IDE settings. Cursor now separates Project Rules from User Rules. Project Rules belong in the repository. User Rules are the global personal preferences that stay in a developer’s Cursor environment.

This guide uses the current Cursor Rules documentation and Cursor Cloud Agent setup documentation as the source of truth.

The short answer

Use AGENTS.md for instructions that should remain readable, portable, and useful across Cursor, Codex, Claude Code, and other coding agents.

Use .cursor/rules/*.mdc when Cursor needs one of these behaviors:

• always apply a rule;
• attach it when a file matches a glob;
• let Agent select it from a description;
• apply it only when a developer mentions it;
• reference Cursor-specific files or workflows.

Most teams do not need to choose only one. A good default is:

repository/
├── AGENTS.md
├── frontend/
│   └── AGENTS.md
├── .cursor/
│   ├── rules/
│   │   ├── react-components.mdc
│   │   └── database-migrations.mdc
│   └── environment.json
└── scripts/
    └── validate.sh

The root AGENTS.md owns the shared operating contract. Nested AGENTS.md files narrow that contract by directory. Cursor Project Rules add selective Cursor behavior without duplicating the shared rules.

The corrected comparison

The important correction is the middle column: Cursor Project Rules are not merely local settings. Cursor explicitly documents them as version-controlled files scoped to the codebase.

What AGENTS.md is best at

AGENTS.md works best as the repository’s readable operating manual. It has no activation metadata, so humans and tools can inspect it without understanding a vendor-specific format.

A useful root file answers four questions:

1. What does this repository do?
2. Where should an agent start reading?
3. What must not change without approval?
4. Which exact commands prove a change is correct?

# Repository contract

This service processes subscription events and writes billing state.

## Read first

- `src/http/` owns request parsing.
- `src/billing/` owns billing decisions.
- `docs/architecture.md` describes event flow and retry behavior.

## Boundaries

- Do not edit generated clients under `src/generated/`.
- Do not create or rewrite migrations without approval.
- Never log tokens, payment details, or webhook secrets.

## Validation

- Application change: `npm test && npm run typecheck && npm run build`
- API contract change: `npm run test:contract`
- Documentation-only change: `npm run lint:docs`

This content remains useful if the team moves between Cursor, Codex, Claude Code, or a CI-based agent. It also gives reviewers a stable contract against which they can evaluate agent output.

Nested AGENTS.md is now a first-class Cursor pattern

Cursor supports AGENTS.md in subdirectories. Parent instructions combine with the more specific file, and the more specific instructions take precedence for work in that subtree.

repository/
├── AGENTS.md                 # repository-wide contract
├── frontend/
│   └── AGENTS.md             # UI validation and design-system rules
└── backend/
    └── AGENTS.md             # API, migration, and service-boundary rules

Use nesting when ownership and validation differ by directory. Do not copy the entire root file into every subtree. The nested file should add only the local delta.

What Cursor Project Rules are best at

Cursor Project Rules live in .cursor/rules and must use the .mdc extension. Their frontmatter controls activation.

Cursor documents four useful modes:

• Always Apply — included in every chat session;
• Apply Intelligently — selected when Agent considers the description relevant;
• Apply to Specific Files — attached when files match configured globs;
• Apply Manually — included when someone mentions the rule.

Example: file-scoped frontend rule

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports.
- Reuse components from `src/design-system/` before adding a new primitive.
- Run `npm run test:components` and `npm run build` before handoff.
- Do not edit generated icon files under `src/generated/icons/`.

Example: relevant-on-demand migration rule

---
description: Database migration safety and reversible rollout rules
alwaysApply: false
---

- Every migration needs a verified rollback path.
- Never combine a destructive schema change and application cutover in one step.
- Run `npm run migration:validate` before handoff.
- Stop and request review before applying changes outside a disposable database.

A plain .md file inside .cursor/rules is ignored by the Project Rules system. If you want plain Markdown without rule metadata, use AGENTS.md instead.

What belongs in each place

The cleanest split is based on authority, not convenience.

The last row prevents a common mistake: rules should point to executable checks, not replace them. If a formatting rule can be enforced by a linter, make the linter canonical and tell the agent which command to run.

A practical setup for Cursor

Step 1: establish one portable contract

Start with a root AGENTS.md. Keep it short enough to scan and link to deeper source-of-truth documents instead of copying them.

Include:

• repository purpose;
• entry points and ownership boundaries;
• exact install, test, lint, type-check, and build commands;
• generated-file rules;
• approval gates for migrations, security, billing, infrastructure, and destructive operations;
• a handoff requirement that reports commands run and known omissions.

The AGENTS.md template provides a copyable baseline.

Step 2: add local deltas, not duplicated manuals

If frontend/ and backend/ have different validation surfaces, use nested AGENTS.md files. If Cursor needs a file-pattern rule, use an .mdc file with globs.

Do not express the same command or safety boundary in three places. Pick one canonical source and make other files reference it.

Step 3: make the environment reproducible

Local Agent can only validate what the developer environment can run. Cloud Agents need a reproducible environment as well.

Cursor supports a repository-level .cursor/environment.json. It can reference a Dockerfile and define installation behavior for Cloud Agent builds.

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "npm ci"
}

Keep long-running services out of the install step. Document how to start required services, then make the validation commands runnable from the repository root.

Cursor’s Cloud Agent documentation also says Cloud Agents read AGENTS.md, so cloud-only setup or test differences can be documented in a clearly labeled section when necessary.

Step 4: use hooks for control, not as hidden documentation

Project hooks live in .cursor/hooks.json. They can observe or control stages such as shell execution, file edits, tool use, and agent completion.

Hooks are useful for policy boundaries, but hidden enforcement creates confusing failures. Keep the underlying script in the repository, document the command in AGENTS.md, and make the hook call that same script.

For a security-critical blocking hook, review failure behavior deliberately. Cursor’s hook documentation notes that hook failures are fail-open by default unless failClosed: true is configured for supported definitions.

Step 5: test in a fresh session

Do not validate repository instructions in the same conversation that created them. Start a fresh Cursor session and ask it to:

1. summarize the repository and its boundaries;
2. identify the validation command for one frontend and one backend change;
3. explain which files are generated;
4. propose a small change without editing;
5. report which rules it used.

Then run a bounded task and verify the handoff independently.

How to migrate from legacy .cursorrules

Treat migration as an authority cleanup, not a filename conversion.

1. Classify every instruction

Move an instruction to:

• AGENTS.md if it is portable repository truth;
• nested AGENTS.md if it belongs to a directory subtree;
• .cursor/rules/*.mdc if it needs Cursor activation metadata;
• a linter, test, or script if it is executable policy;
• Cursor User Rules if it is only a personal preference.

2. Remove contradictions

Search for the same rule across README.md, CONTRIBUTING.md, AGENTS.md, .cursor/rules, and CI configuration. Choose one owner for each command and boundary.

3. Verify before deleting the legacy file

Run a fresh Cursor session against representative tasks. Confirm the expected root, nested, and file-scoped instructions apply. Remove .cursorrules only after the new contract passes that test.

Common failure modes

Treating Project Rules as user-local preferences

This was true of some older mental models, but it is not the current Project Rules design. Files under .cursor/rules are intended to be version-controlled and shared.

Putting a plain Markdown file in .cursor/rules

Project Rules require .mdc. A file such as .cursor/rules/api-guidelines.md is ignored by the rules system.

Copying the same rule into AGENTS.md and several .mdc files

Duplication creates drift. A changed command lands in one file while the other keeps sending agents toward an obsolete check.

Using prose where an executable gate exists

“Keep formatting clean” is weaker than npm run lint. The rule should name the command; the command should enforce the behavior.

Assuming local success proves Cloud Agent readiness

A local shell may contain packages, credentials, services, or caches that a cloud environment lacks. Encode reproducible setup, keep secrets outside the repository, and test from a clean environment.

Loading every rule into every task

More context is not automatically better. Use nested instructions and rule activation to keep irrelevant guidance out of a task.

Repository readiness checklist for Cursor

• Root AGENTS.md defines purpose, entry points, boundaries, and exact validation commands.
• Nested AGENTS.md files contain only subtree-specific deltas.
• Cursor Project Rules use .mdc, not .md.
• Every .mdc rule has the activation behavior you intend.
• Shared rules are committed to version control.
• Personal preferences stay in Cursor User Rules.
• Executable policy lives in tests, linters, or scripts rather than prose alone.
• Cloud setup is reproducible through repository configuration when Cloud Agents are used.
• Hook behavior and failure mode are reviewed before hooks block commands.
• A fresh session can identify the right instructions and validation path.
• Final handoff lists commands run, results, omissions, and residual risks.

If several of these are missing, repository-harness provides a tool-agnostic starting structure for instructions, validation, handoff, and durable repository context.

FAQ

Should I use AGENTS.md or Cursor Project Rules?

Start with AGENTS.md when the instruction is a readable repository contract that should work across coding tools. Add version-controlled Cursor Project Rules when Cursor needs file-pattern scoping, automatic relevance selection, manual invocation, or Cursor-specific workflows.

Are Cursor Project Rules stored only on one developer’s machine?

No. Modern Cursor Project Rules live as .mdc files under .cursor/rules and are designed to be committed to version control. Cursor User Rules are the local, global preferences that remain tied to a user’s environment.

Does Cursor support nested AGENTS.md files?

Yes. Cursor supports AGENTS.md at the project root and in subdirectories. When work targets a nested area, parent instructions are combined with more specific nested instructions, and the more specific instructions take precedence.

Can AGENTS.md and Cursor Project Rules coexist?

Yes. Use AGENTS.md as the portable repository contract, then add focused .cursor/rules/*.mdc files for Cursor-specific scoping or workflows. Avoid copying the same rule into both places because duplicated instructions drift.

Does a Markdown file inside .cursor/rules work as a Project Rule?

No. Cursor Project Rules must use the .mdc extension and rule frontmatter. A plain .md file inside .cursor/rules is ignored by the Project Rules system. Use AGENTS.md when plain Markdown is preferable.

What should a repository add for Cursor Cloud Agents?

Keep durable instructions in AGENTS.md or Project Rules, encode reproducible environment setup in .cursor/environment.json when needed, and add exact validation commands. Project hooks in .cursor/hooks.json can enforce selected checks, but the underlying test and build commands should remain runnable outside Cursor.

Should I migrate a legacy .cursorrules file?

Yes. Move portable repository guidance into AGENTS.md and convert Cursor-specific or path-scoped guidance into .mdc files under .cursor/rules. Validate the result in a fresh session and remove the legacy file only after the new instructions are applied correctly.

Official sources

• Cursor Rules — rule types, .mdc format, activation modes, version control, and nested AGENTS.md
• Cursor Cloud Agent setup — .cursor/environment.json, Dockerfile-based builds, and Cloud Agent instructions
• Cursor Hooks — project hooks, lifecycle events, and enforcement behavior
• Using Agent in Cursor CLI — repository instructions used by the CLI

Related CodeHarness guides

• How to Write an AGENTS.md That Actually Works
• Coding-Agent Context File Formats Compared
• How to Manage Multiple Coding Agents in One Repository
• How to Audit a Repository for Agent-Readiness
• What Is an Agent-Ready Repository?