The problem: the assistant starts from zero in every conversation
For the third time this week you asked Cursor for an Angular component and for the third time it answered with
@Input decorators instead of the input() functions you use in the project. It is not carelessness:
a language model keeps no memory from one request to the next, and the conventions your team has in its head are
not written anywhere it can read. Cursor rules exist for this: they are persistent instructions that Cursor includes at the start of
the model's context, and so the same advice you would give a new
colleague on the first day, written once in a file and repeated on its own in every conversation.
This article explains how rules are built today, according to the official documentation read on 2026-11-13: the four types, the three fields that decide when a rule enters the context, a complete example with a small program that applies the decision table to your files, and the mistakes that make a rule seem not to work. If you have not yet seen how to work with the Agent, start from the opening guide of the series.
Four types of rule, four places where they live
The rules page lists four types, which differ by who owns them and where they are stored.
- Project rules: files in
.cursor/rules, versioned with the code and valid for that repository. - User rules: global preferences of your Cursor environment, used by the Agent in every project.
- Team rules: rules for the whole organisation, managed from the dashboard, available on the Team and Enterprise plans.
- AGENTS.md: a plain markdown file in the project root, a lighter alternative to project rules.
The distinction that matters is who must be able to change the rule. A repository convention (how files are named, which pattern to use for errors) belongs to the project and must travel with the code, so that whoever clones the repository gets it; a personal preference such as the language of the answers belongs to you; a company rule belongs to whoever administers the team. When the sources overlap, the documentation says that they all apply together and that in case of conflict the order team, project, user prevails. One thing that is often taken for granted: according to the same page, rules do not affect Tab or the other artificial intelligence features, only the Agent.
Anatomy of a project rule
Every project rule is a file with the .mdc extension inside .cursor/rules, in a
folder of your choice (you can organise them in subfolders). The file starts with a header block, the
frontmatter, and continues with the instructions in markdown. One detail that has cost many people time: a
.md file in the same folder is ignored, because it lacks the header that says when to apply it.
If you prefer plain markdown, the documentation points to AGENTS.md.
The header has three fields: alwaysApply, description and globs. They are not
independent, and the table the documentation gives for their combination is the most useful point of the whole page.
| alwaysApply | description | globs | Behaviour |
|---|---|---|---|
| true | irrelevant | irrelevant | Always included; globs and description are ignored |
| false | irrelevant | present | Attached when a matching file is in the context |
| false | present | absent | The Agent reads the description and includes it if needed |
| false | absent | absent | Included only if you call it with @rule-name in chat |
Read it as a cascade. If alwaysApply is true, the rest does not matter. If it is not, globs
win over the description, and only without globs does the description become the way the Agent chooses. A
description written for a rule that already has globs, according to the table, does not change the behaviour:
the description serves only the rules you want to leave to the Agent's decision. In the interface the same
four cases appear as a drop-down menu ("Always Apply", "Apply Intelligently", "Apply to Specific Files",
"Apply Manually"), which sets these fields for you.
A sample project: four rules and a loader
To see the table in action I built a sample folder, an imaginary Angular application with a shopping cart, and put four rules in it: a universal one, one for components, one on HTTP services and one on database migrations. They are written the way you would write them, short and with verifiable instructions.
# ===== .cursor/rules/base.mdc
---
alwaysApply: true
---
- Reply in Italian and write code comments in English.
- Never edit the generated files in `dist/`.
- Before proposing a change to a service, read the file that defines it.
# ===== .cursor/rules/components.mdc
---
globs: src/app/**/*.component.ts, src/app/**/*.component.html
alwaysApply: false
---
- Use standalone components with `ChangeDetectionStrategy.OnPush`.
- For inputs and outputs use the `input()` and `output()` functions, not the decorators.
- In templates use `@if` and `@for`, not `*ngIf` and `*ngFor`.
# ===== .cursor/rules/services/http.mdc
---
description: Conventions for services that call the backend with HttpClient
alwaysApply: false
---
- Each service lives in a `*.service.ts` file and returns typed Observables.
- HTTP errors are converted into an object with `code` and `message`, never into a string.
- For the basic structure read `@service-template.ts` before creating a new one.
# ===== .cursor/rules/migrations.mdc
---
alwaysApply: false
---
- Every migration has an `up` part and a `down` part.
- Never change the type of a column in place: add a column, copy the data, then drop the old one.
The first has only alwaysApply: true: it holds for every conversation, so it contains only things that are
really true everywhere. The second has the globs and is attached only when you work on a component. The third
has a description written with the Agent in mind, which reads it and decides: the description must say
when the rule is needed, not summarise its content. The fourth has no field at all and stays out until
you write @migrations, which makes it suitable for delicate procedures that you do not want to see applied on
the Agent's initiative.
The program below is a minimal loader that applies the table: it reads every file in
.cursor/rules, discards those without the .mdc extension or without a header, classifies the
rule into the four types and says, given the list of files present in the context, which rules would come in. It is not
Cursor's code: it is the documentation's table translated into code, and it serves to check your rules before
discovering a mistake in a conversation. To compare paths with the globs it uses
glob.translate, available in recent versions of Python (here 3.14.4).
"""Apply the decision table from the Cursor documentation (consulted on 2026-11-13) to .cursor/rules."""
import glob, re, sys
from pathlib import Path
def read(path):
text = path.read_text(encoding="utf-8")
m = re.match(r"---\n(.*?)\n---\n(.*)", text, re.S)
if not m:
return None, text
fields = {}
for line in m.group(1).splitlines():
key, _, value = line.partition(":")
fields[key.strip()] = value.strip()
return fields, m.group(2)
def kind(fields):
if fields.get("alwaysApply") == "true":
return "always" # globs and description ignored
if fields.get("globs"):
return "per-file" # attached if a matching file is in the context
if fields.get("description"):
return "intelligent" # the agent reads the description and decides
return "manual" # only with @rule-name
def matches(globs, file):
patterns = [g.strip() for g in globs.split(",")]
return any(re.fullmatch(glob.translate(g, recursive=True, include_hidden=True), file) for g in patterns)
def main(root, context):
rules = []
for p in sorted(Path(root, ".cursor/rules").rglob("*")):
if p.is_dir():
continue
name = p.relative_to(Path(root, ".cursor/rules")).as_posix()
if p.suffix != ".mdc":
print(f"{name}: IGNORED, the extension is not .mdc")
continue
fields, body = read(p)
if fields is None:
print(f"{name}: IGNORED, the header is missing")
continue
if fields.get("globs", "").startswith("["):
print(f"{name}: WARNING, globs is a YAML list; the documentation shows a string with comma-separated patterns")
rules.append((name, kind(fields), fields))
print("context:", ", ".join(context) if context else "(no file)")
for name, t, fields in rules:
if t == "always":
outcome = "included"
elif t == "per-file":
outcome = "included" if any(matches(fields["globs"], f) for f in context) else "not included"
elif t == "intelligent":
outcome = "the agent decides: " + fields["description"]
else:
outcome = "only with @" + name.removesuffix(".mdc").split("/")[-1]
print(f" {name:20} [{t}] {outcome}")
if __name__ == "__main__":
main(sys.argv[1], sys.argv[2:])
There are two functions to look at. kind() is the table, with the same four cases and in the same order.
matches() splits the globs field on the comma, as the documentation does in its examples
with several patterns, and compares each piece with the file's path. If you remove the split on the comma, a rule with
two patterns stops matching both. I ran the program twice for each context file, with
identical output, in two situations: you are editing a component, or a service.
# $ python3 -I load_rules.py project src/app/cart/cart.component.ts
# bad-globs.mdc: WARNING, globs is a YAML list; the documentation shows a string with comma-separated patterns
# notes.md: IGNORED, the extension is not .mdc
# context: src/app/cart/cart.component.ts
# bad-globs.mdc [per-file] not included
# base.mdc [always] included
# components.mdc [per-file] included
# migrations.mdc [manual] only with @migrations
# services/http.mdc [intelligent] the agent decides: Conventions for services that call the backend with HttpClient
#
# $ python3 -I load_rules.py project src/app/cart/cart.service.ts
# bad-globs.mdc: WARNING, globs is a YAML list; the documentation shows a string with comma-separated patterns
# notes.md: IGNORED, the extension is not .mdc
# context: src/app/cart/cart.service.ts
# bad-globs.mdc [per-file] not included
# base.mdc [always] included
# components.mdc [per-file] not included
# migrations.mdc [manual] only with @migrations
# services/http.mdc [intelligent] the agent decides: Conventions for services that call the backend with HttpClient
With the component in the context, the universal rule and the components rule come in; with the service only the
universal one comes in, and the services rule is left to the Agent's decision, while the migrations rule
waits for the explicit mention. Note two other things: notes.md is ignored because of its extension, and
bad-globs.mdc produces a warning. That file, which writes the globs as a YAML list, is
shown below: the documentation always shows globs as a string with the patterns separated
by commas and does not describe the list form. I have not tried how Cursor treats it, so when in doubt use the
documented form.
---
globs: ["**/*.spec.ts"]
alwaysApply: false
---
- Each test describes a single behaviour.
Writing globs: testing the patterns
The globs are where mistakes happen most often, because *.ts and
**/*.ts look equivalent and are not. The documentation defines them like this: a single
asterisk is one segment of a file name, the double asterisk is any number of folders. The following program
tests five patterns from the official list against five paths.
import glob, re
patterns = ["*.ts", "**/*.ts", "src/**", "src/**/*.tsx", "tailwind.config.*"]
paths = ["main.ts", "src/main.ts", "src/app/ui/button.tsx", "src/README.md", "tailwind.config.js"]
for pat in patterns:
rx = re.compile(glob.translate(pat, recursive=True, include_hidden=True))
found = [p for p in paths if rx.fullmatch(p)]
print(f"{pat:20} -> {found}")
The aim is to see where each pattern stops. The output compares what matches each one.
# *.ts -> ['main.ts']
# **/*.ts -> ['main.ts', 'src/main.ts']
# src/** -> ['src/main.ts', 'src/app/ui/button.tsx', 'src/README.md']
# src/**/*.tsx -> ['src/app/ui/button.tsx']
# tailwind.config.* -> ['tailwind.config.js']
*.ts finds only main.ts in the root; to catch src/main.ts as well you need
**/*.ts. A pattern such as src/** takes everything under src,
documentation included, and for this reason it is usually better to narrow it with an extension, as in
src/**/*.tsx. The result agrees with the documentation's cases, but it is Python's semantics:
for the last word on Cursor's behaviour trust its page.
Pointing to a file instead of copying it
In the services rule there is @service-template.ts. The documentation explains how the
reference works: the content of the rule reaches the Agent as it is, and the mention of a file tells it where to look,
but the file is not inserted into the prompt; the Agent reads it with its own tools when it needs it. Two consequences.
First, a hundred-line code template referenced this way does not weigh on the context when the rule is inactive and does not
go stale in two copies. Second, whatever must always be present has to be written in the body of the rule: a
reference is not a guarantee that the file will be read.
What to put in a rule and what to leave out
The same page gives writing guidance that is worth keeping together, because it says how small a rule should be.
- Rules under 500 lines, split into several composable rules when they grow.
- Concrete examples or reference files, not vague guidance.
- No copies of whole style guides: for those you need a linter, because the Agent already knows the common conventions.
- No list of all the commands: the Agent knows npm, git and pytest.
- No instructions for edge cases that rarely come up.
The common thread is that a rule costs context in every conversation it enters, so it is worth it only if it corrects a
mistake the Agent really makes, repeatedly. The documentation's advice is to start with little and add
a rule when you see the Agent repeat the same mistake; when you see it again with the rule already written, the
flaw is in the rule and must be fixed, not multiplied. As a first try you can ask the Agent to write the
rule for you with /create-rule, or add it from the Rules entry of Customize.
AGENTS.md, user rules and team rules
AGENTS.md is a markdown file with no header and no metadata. Cursor reads it in the root and in
subfolders: an AGENTS.md inside frontend/ applies to the files of that folder and of its
children, and the more specific instructions prevail over those of the upper levels. It is the right choice if you want
instructions readable by anyone without learning the four rule types; we will use it in the
workflow on an Angular project.
User rules are set from Customize and hold everywhere: the documentation describes them as suited to preferences
such as the style of the answers.
Team rules are created from the dashboard and have two switches that change a lot: "Enable this rule immediately", otherwise the rule stays a draft, and "Enforce this rule", which prevents members from turning it off from Customize. This does not make it a security control: the documentation warns that some teams use enforced rules in compliance processes, but that the guidance given to a model should not be the only security control. To import rules from a GitHub repository it is not enough to copy them: they have to be packaged in a plugin and published through a marketplace.
Frequently asked questions
Why is my rule not being applied?
Check the type first: an "Apply Intelligently" rule needs a description, a per-file rule needs a pattern that matches the files in context, and a file without the .mdc extension is ignored. This article's loader repeats the three checks.
Do rules also apply to Tab completion?
No. The documentation says that rules do not affect Cursor Tab or the other artificial intelligence features: they matter for the Agent.
What happened to the .cursorrules file?
The rules page currently in force no longer describes it: it lists project rules in .cursor/rules, user rules, team rules and AGENTS.md. If you have an old file, move its content into an .mdc rule or into AGENTS.md.
What you can do now
You can choose the rule type for each convention, write the right header after reading the cascade of the three fields, test the patterns before trusting them and keep every rule small, versioned and tied to a real mistake. The next step is to give the Agent a whole task and watch how it uses these rules: we see it in the article on Agent Mode.
The same series also includes Cursor vs Windsurf vs VS Code + Copilot in 2026.
Sources
- Cursor, documentation: Rules - four rule types, .mdc extension, table of alwaysApply, description and globs, file references, best practices, AGENTS.md, team rules, FAQ, consulted on 2026-11-13
- Cursor, documentation: Agent mode - rules hold in all modes (Agent, Ask, Plan, Debug), consulted on 2026-11-13
- Python: glob module - glob.translate with recursive and include_hidden, used in the two sample programs, consulted on 2026-11-13
The two programs were run with Python 3.14.4 in a temporary folder outside the repository, twice each with identical output. They apply the documentation's table and are not Cursor's code: nothing was tried inside the editor, because Cursor was not installed. The list format of globs and the fate of the old .cursorrules file are declared in the text as not verified.

Commenti
Caricamento commenti...
Sign in to comment