wbstorm

How to write Cursor Rules: project file and how the agent uses it

Write a .mdc in .cursor/rules, pick an apply mode, keep the body actionable. Agent injects matching rules at the start of context.

Cursor Agent does not keep memory between chats. If you paste “do not rewrite the router” a third time, put it in a project rule so the next session starts with it.

Official docs call this Cursor Rules. Project rules live in .cursor/rules and must use the .mdc extension. A plain .md in that folder is ignored. This is an editor how-to, not a brainstorm-product manual.

Create .mdcSet frontmatterAgent injects it

What a project rule is

See cursor.com/docs/context/rules. Of the four rule sources, a repo file is enough to start. When a rule applies, its body sits at the start of the model context.

.mdc
Project rule extension
4 modes
How it attaches
Start
Where it is injected
SourceWhere it livesWhen it enters context
Project Rules.cursor/rules/*.mdcFrom frontmatter
User RulesCustomize → RulesAgent (Chat), all projects
Team RulesDashboard (Team / Enterprise)All repos; can be enforced
AGENTS.mdRoot or subdirectoryPlain markdown, no frontmatter

Write the first rule in four steps

  1. 1

    Create the file

    Add .cursor/rules/your-name.mdc in the repo. Or type /create-rule in Agent, or open Customize → Rules → Add Rule. Folders are fine. The extension must be .mdc.

  2. 2

    Pick an apply mode

    alwaysApply: true on every chat. globs when a matching file is in context. Description only: Agent decides. All empty: only when you @rule-name in chat.

  3. 3

    Write an actionable body

    Write it like an internal doc: never-lists, naming, directory boundaries. Point at examples with @filename.ts instead of pasting the file. Official cap: keep a rule under 500 lines.

  4. 4

    Commit and check

    Check the rule into git so the team shares it. Confirm status in Customize. If Agent still misses it, @-mention the rule in the chat.

What belongs in the body

01

Conventions a linter cannot catch

Examples: never edit generated files; new services return structured errors. Leave common style to ESLint or rustfmt. Do not paste a whole style guide.

02

Architecture boundaries

Which layer may touch the database, which folders must not import each other. Agent already knows git and npm. Skip everyday commands.

03

Pointers to repo examples

Use @ to reference a template that already exists. When the code changes, the rule stays short. Add a rule when Agent repeats a mistake — do not start with twenty files.

---
description: TypeScript conventions for this repo
globs: **/*.{ts,tsx}
alwaysApply: false
---

# TypeScript
- Prefer named exports
- Do not edit files under dist/
- New API clients follow @src/api/client.ts

How the agent uses the rule

After a match, the rule body sits at the start of context for codegen, edit explanations, and workflows. Official conflict order is Team Rules → Project Rules → User Rules; earlier sources win. Rules do not affect Cursor Tab. User Rules do not apply to Inline Edit (Cmd/Ctrl+K).

When to use AGENTS.md instead

If you only need a readable note, put AGENTS.md in the repo root or a subdirectory. Nested files merge when you work in that tree; more specific files win. For glob or manual-@ control, stay on .mdc.

When the rule is in and you need a shared sketch, wbstorm is a browser room ID — see create or join a room and whiteboard basics.

Why is my rule not applying?

Check the type. Apply Intelligently needs a description. File-scoped rules need a glob that matches a path already in context. A plain .md in .cursor/rules is ignored.

Do rules affect Tab completion?

Official FAQ: rules do not affect Cursor Tab or other non-Agent features. User Rules also skip Inline Edit.

Can a rule reference other files?

Yes. Write @filename.ts in the rule body. You can also @-mention a rule in chat to attach it by hand.

Is this a wbstorm feature guide?

No. This article is only about Cursor project rules. wbstorm is a browser brainstorm room and is unrelated to the rules file.

Create room