Cursor Rules Guide: .cursor/rules, .mdc Files and How They Relate to AGENTS.md

By og.cc.cd · Published 2026-10-20 · Updated 2026-10-20 · 4 min read

Cursor gives you two ways to tell its agent how your project works: structured rules in .cursor/rules, and a plain AGENTS.md. This guide explains the rule format from Cursor’s documentation, when each kind of rule loads, and how to combine rules with AGENTS.md without repeating yourself.

Generate an AGENTS.md →All guides

Four kinds of rules

Cursor’s Rules documentation lists four types (Cursor Rules):

When a rule applies, its content is placed at the start of the model context. Rules exist because models keep no memory between completions; they turn repeated instructions into persistent, reusable context.

Project rules: .mdc files with frontmatter

Each project rule is an .mdc file in .cursor/rules (sub-folders are fine). The extension matters: Cursor’s docs say a plain .md file in that folder is ignored by the rules system, because it has no frontmatter. Use AGENTS.md if you want plain markdown.

.cursor/rules/
  react-patterns.mdc       # recognised
  api-guidelines.md        # ignored (wrong extension)
  frontend/
    components.mdc         # folders are fine

Three frontmatter fields decide when a rule is included:

A file-scoped rule, as in Cursor’s own example:

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

- Use named exports, not default exports
- Co-locate styles in a module CSS file next to the component
- Keep components under 200 lines

Globs use the usual patterns: **/*.ts for every TypeScript file, src/** for everything under src/, and comma-separated lists such as docs/**/*.md, docs/**/*.mdx.

Referencing files

You can mention a file such as @service-template.ts in a rule. Cursor is explicit that the file is not inlined: the mention tells the agent where to look, and it reads the file with its tools when it needs it. Anything that must always be in context belongs in the rule body itself.

Creating and maintaining rules

• Type /create-rule in Agent and describe what you want, or use Customize → Rules → Add Rule. Both write a file to .cursor/rules.
• Keep each rule under 500 lines and split large ones into composable rules.
• Do not paste whole style guides (use a linter) or document every common command; the agent already knows npm, git and pytest.
• Start small and add a rule when you see the agent make the same mistake twice. Commit rules so the whole team benefits.

User and Team rules

User Rules are free-text preferences that follow you across projects, such as “reply concisely”. They apply to Agent (Chat) only — the docs note they are not used by Inline Edit (Cmd/Ctrl+K), and rules in general do not affect Cursor Tab. Team Rules are managed from the dashboard on Team and Enterprise plans, can be enforced so members cannot switch them off, and support globs. When several apply, the order is Team → Project → User, with earlier sources winning conflicts.

A small starter set

For a typical web app, three short rules cover most of what teams end up writing. These are our suggestions, using the frontmatter fields described above:

# .cursor/rules/project.mdc
---
alwaysApply: true
---
- Run `pnpm test` before saying a task is done
- Never edit files in `dist/` or `generated/`

# .cursor/rules/api.mdc
---
globs: src/api/**/*.ts
alwaysApply: false
---
- Validate request bodies with zod at the handler boundary
- Return { code, message } errors, never raw strings

# .cursor/rules/migrations.mdc
---
description: How to write and review database migrations
alwaysApply: false
---
- Every migration needs both up and down steps
- Read @migrations/TEMPLATE.sql before writing one

The first is always on and tiny; the second loads only when API files are in play; the third waits until the agent decides a migration is involved. That keeps the context lean, which matters because every applied rule sits at the start of the prompt on every request.

Moving older instructions over

If your repository still has instructions in another place — an older single rules file, a long README section, or notes for a different agent — the current Rules documentation only describes the locations above. Move tool-neutral guidance into AGENTS.md, split the Cursor-specific parts into focused .mdc files, and delete the old copy so the two cannot disagree.

Where AGENTS.md fits

Cursor reads AGENTS.md from the project root and from sub-directories. Nested files apply when the agent works in that directory, are combined with their parents, and the more specific file takes precedence. AGENTS.md is also read by other coding agents, so it is the natural home for anything tool-neutral. A sensible split:

• AGENTS.md — setup, build and test commands, project layout, conventions every agent should follow. Generate a starting point with our AGENTS.md generator and read what AGENTS.md is.
• .cursor/rules — Cursor-specific behaviour that benefits from scoping: rules that should load only for certain files (globs), only when relevant (description), or only on request (@-mention).
• User Rules — personal style preferences that should not live in the repository.

If a rule seems to be ignored, check its type first: “Apply Intelligently” needs a description, and “Apply to Specific Files” only loads when a file matching the glob is in context.

Sources

Vendor features and prices were checked against these official pages on 2026-10-20. Products change; if something here no longer matches, the official page is right.

• Cursor Docs — Rules
  https://cursor.com/docs/rules
• AGENTS.md — official site
  https://agents.md/

Related guides

• Migrating from MiMo V2.5 to V2.6: Model IDs, Prices and API Examples
• How to Get an LLM API Key: OpenAI, Claude, Gemini, DeepSeek, Qwen, Kimi, GLM and More
• How to Get an OpenAI API Key: Steps, Region Rules, Billing and First Request