# Write Cursor project rules that actually load when you need them

> Put rules in .cursor/rules as .mdc files, set alwaysApply, globs and the description on purpose, and test that the agent picks each rule up.

- **Category:** [Coding](https://stepgleam.com/categories/coding)
- **Difficulty:** Intermediate
- **Time:** ~25 minutes
- **Tools:** Cursor, Git
- **Reliability score:** 74/100
- **Steps:** 5
- **Last updated:** 2026-10-26
- **Published:** 2026-10-26

## Tools used

- [Cursor](https://cursor.com/docs) — Loads project rules into the agent context
- [Git](https://git-scm.com) — Shares rules with the team

## 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.

## 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.

## Steps

### Step 1: Put project rules in .cursor/rules as .mdc files

**Tool:** Cursor

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."*

[Open step 1](https://stepgleam.com/guides/write-cursor-project-rules-that-actually-load#step-1)

### Step 2: Set the trigger deliberately

**Tool:** Cursor

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."*

**Why this works:** A vague description means the agent may never fetch the rule.

**Prompt:**

```
---
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
```

[Open step 2](https://stepgleam.com/guides/write-cursor-project-rules-that-actually-load#step-2)

### Step 3: Edit .mdc files in a plain editor if the UI misbehaves

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

[Open step 3](https://stepgleam.com/guides/write-cursor-project-rules-that-actually-load#step-3)

### Step 4: Test that a rule loads

**Tool:** Cursor

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.

[Open step 4](https://stepgleam.com/guides/write-cursor-project-rules-that-actually-load#step-4)

### Step 5: Use AGENTS.md if you want something simpler

**Tool:** Cursor

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

[Open step 5](https://stepgleam.com/guides/write-cursor-project-rules-that-actually-load#step-5)

## Pro tips

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

## Common mistakes

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

## FAQ

### 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.

---

Canonical guide: https://stepgleam.com/guides/write-cursor-project-rules-that-actually-load
Read this guide as Markdown: https://stepgleam.com/guides/write-cursor-project-rules-that-actually-load.md