Write Cursor project rules that actually load when you need them

Tools used

CursorLoads project rules into the agent context
GitShares rules with the team

Step navigator0/5 done

0 of 5 steps done

What you'll get

A small set of committed .mdc rules, each with a trigger you chose and checked.

Who this is for

Cursor users whose rules seem to be ignored.

Read this first

Before you start

A widely read r/cursor deep dive found that rules in .cursor/rules don't all switch on just by being there: whether a rule is added to the context and whether it is used depend on alwaysApply, globs and the description. Cursor's docs describe the same rule types.

Step 1 of 5 · Coding

Put project rules in .cursor/rules as .mdc files

Done

Cursor's docs: project rules "live in .cursor/rules as .mdc files and are version-controlled." The deep dive's reason to commit them: "Teams can collaborate using shared rules."

Write Cursor project rules that actually load when you need them — guide thumbnail

Step 2 of 5 · Coding

Set the trigger deliberately

Done

Each rule's front matter has description, globs and alwaysApply. Per the deep dive, alwaysApply and globs decide whether a rule is injected into the context, and the description decides whether the agent fetches and uses it. Asked whether rules in the folder activate automatically, the author's answer is: "No."

Copy-ready promptCursor

---
description: Backend API conventions. Use when editing files in src/api.
globs: src/api/**
alwaysApply: false
---
- Validate inputs at service boundaries
- Return { code, message } on errors

Why this works

A vague description means the agent may never fetch the rule.

Step 3 of 5 · Coding

Edit .mdc files in a plain editor if the UI misbehaves

Done

The deep dive found Cursor's built-in editor for .mdc files buggy and recommends "Editing these files with external tools like VSCode."

Step 4 of 5 · Coding

Test that a rule loads

Done

The author's test: put a line in the rule like "When this rule loads, input: 'Rule loaded: global.mdc.'" and see whether the agent prints it in a new chat.

Step 5 of 5 · Coding

Use AGENTS.md if you want something simpler

Done

Cursor also reads AGENTS.md, which its docs call a "Simple alternative to .cursor/rules."

End of guide · Reviewed Oct 26, 2026

Pro tips2

Remove the test line once you have confirmed the rule loads.
Keep one topic per rule file.

Common mistakes2

Assuming every file in .cursor/rules applies to every chat.
A description that does not say when the rule is relevant.

FAQ2

User rules vs project rules?

User rules follow you across projects; project rules belong to one repo and are committed.

Do rules apply the same in every mode?

The deep dive found they do not apply equally across ask, edit and agent modes.

Tools used

Before you start

Step-by-step instructions

Related field guides.

Get a second-opinion review from a fresh session or another model

Set up Claude Code hooks for formatting, tests and protected files

Turn a checklist you keep forgetting into a Claude Code skill