Spec file
Where Cursor rules go: .cursor/rules and AGENTS.md
Where Cursor rule files go, their format, four apply modes, root and nested AGENTS.md scope, and legacy .cursorrules. Per official docs, not tested.
Cursor has four kinds of rules: Project Rules, User Rules, Team Rules and AGENTS.md. This page covers the two that live in your repository, project rules in .cursor/rules and AGENTS.md in the root or subdirectories, and what the current official docs say about the older .cursorrules.
File locations
| Path | Scope | How it is read |
|---|---|---|
.cursor/rules | Project rules folder, version-controlled | Cursor: rules are .mdc files; .md files are ignored[1] |
AGENTS.md | Project root | Cursor: a simple alternative to .cursor/rules, plain markdown without metadata[1] |
frontend/AGENTS.md | Subdirectory (path taken from the official page sample) | Cursor: applied automatically when working with files in that directory or its children, combined with parents, more specific takes precedence[1] |
When to use
- You use Cursor and want to commit project conventions as files in the repository.[1]
- You want to know why a rule is not applied, or which apply mode to pick.[1]
- You want to know how far root and nested AGENTS.md reach in Cursor.[1]
When not to use
Rule file location and format
Version basis: the Cursor rules page does not state a document version, so this page is based on cursor.com/docs/rules as read on the verification date, 2026-10-28; later official changes are not covered.[1]
- Project rules live in .cursor/rules as .mdc files and are version-controlled; you can name a file anything you want.
- The docs say project rules must use the .mdc extension; a plain .md file in .cursor/rules is ignored by the rules system because it has no frontmatter to specify description, globs and alwaysApply. If you prefer plain markdown, the docs suggest AGENTS.md instead.
- Rules can be organised in folders, for example .cursor/rules/frontend/components.mdc.
- Each rule is frontmatter metadata plus content; the frontmatter controls how the rule is applied.
---
description: Frontend component conventions
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports
- Keep components under 200 lines
The four apply modes
| Apply mode | Official description | Frontmatter condition |
|---|---|---|
| Always Apply | Applied to every chat session | alwaysApply is true; globs and description are ignored |
| Apply to Specific Files | When a file matches a specified pattern | alwaysApply is false; the description column shows "—" in the original table; globs is provided; auto-attached when a matching file is in context |
| Apply Intelligently | When Agent decides it is relevant based on the description | alwaysApply is false; description is provided; globs is omitted; Agent reads the description and pulls the rule in when relevant |
| Apply Manually | When @-mentioned in chat, for example @my-rule | alwaysApply is false; description is omitted; globs is omitted; included only when you @-mention the rule in chat (the original table row is false / omitted / omitted, not all three unset) |
- Official FAQ: if a rule is not applied, check the rule type first; for Apply Intelligently make sure a description is defined, and for Apply to Specific Files make sure the file pattern matches the files in question.
- Separate multiple globs with commas, for example docs/**/*.md, docs/**/*.mdx.
The four kinds of rules and their order
| Kind | Where it lives | Official description |
|---|---|---|
| Project Rules | Stored in .cursor/rules in the repository | Version-controlled and scoped to your codebase |
| User Rules | Customize → Rules in Cursor settings | Global to your Cursor environment, used by Agent (Chat) |
| Team Rules | Managed from the team dashboard | Available on Team and Enterprise plans |
| AGENTS.md | Project root or subdirectories | Agent instructions in markdown format, a simple alternative to .cursor/rules |
When several rules apply, the documented order is Team Rules, Project Rules, User Rules; all applicable rules are merged, and earlier sources take precedence when guidance conflicts.[1]
How far root and nested AGENTS.md reach
- Root: AGENTS.md goes in the project root as an alternative to .cursor/rules for simple cases; it is a plain markdown file without metadata.
- Subdirectories: the docs say Cursor supports AGENTS.md in the project root and subdirectories; an AGENTS.md in any subdirectory is applied automatically when working with files in that directory or its children.
- Nesting: instructions from nested files are combined with parent directories, and more specific instructions take precedence.
The sample tree on the official page has AGENTS.md (global), frontend/AGENTS.md, frontend/components/AGENTS.md and backend/AGENTS.md, for the whole project, frontend, components and backend respectively.[1]
The old .cursorrules
The current official docs do not mention .cursorrules, so whether it is still read or has been deprecated is to be confirmed. Per the current official page: project rules go in .mdc files under .cursor/rules, and plain markdown goes in AGENTS.md.[1]
Sources
All links are official pages; verification dates are listed per source, and links point to the version checked.
Related tools
Cursor
A coding agent for understanding repositories, planning features, changing code, and reviewing diffs.