Cursor: project rules (.cursor/rules) (2026)

Project rules are persistent instructions Cursor injects into Agent context depending on how you configure them. They live in `.cursor/rules/` as `.mdc` files with frontmatter (`description`, `globs`, `alwaysApply`), ship with your code and spread across the team without copy-pasted prompts. If you only need simple markdown, `AGENTS.md` at the repo root (or in subfolders) is the official alternative without metadata. A `.cursorrules` file at the root still works in many repos but Cursor treats it as legacy: plan to move its content into an «Always Apply» rule. Docs: https://cursor.com/docs/rules and migration from `.cursorrules`: https://cursor.com/help/customization/rules. This flow takes about 20 minutes and ends with two real rules in your repo plus an Agent check.

1. Steps 1

   Pick the format: .mdc rules, AGENTS.md or legacy

   Before writing files, pick how much structure you need.

   - **`.cursor/rules/*.mdc`**: multiple rules with types (Always, globs, description, manual via @). This is what Cursor documents for teams that want scoped, composable rules. - **`AGENTS.md`**: plain markdown at the root (or nested in subfolders) without frontmatter. Cursor applies it when you work in that path. Fine when you do not need globs yet. - **`.cursorrules`**: single root file, legacy. If you already have one, plan to move its content into a `.mdc` with `alwaysApply: true` and delete `.cursorrules` (see https://cursor.com/help/customization/rules).

   This tutorial uses **`.cursor/rules`**. Keep the reference doc open: https://cursor.com/docs/rules

   What you should see: A one-line note: «mdc for per-folder standards» or «AGENTS.md is enough for now».

2. Steps 2

   Create `.cursor/rules` and your first rule

   At the repo root, create `.cursor/rules/` if it is missing. Two official ways to add rules:

   1. **Customize → Rules → Add Rule** in Cursor’s sidebar (also described in the docs). 2. **New file** `team-basics.mdc` with frontmatter and a markdown body.

   Minimal skeleton:

   ```md --- description: Repo-wide standards alwaysApply: true ---

   - Run `npm test` (or the README script) before calling a change done. - Do not edit `.github/workflows/` unless explicitly asked. ```

   The filename is free; the extension **must** be `.mdc`. A plain `.md` file inside `.cursor/rules` is not picked up by the rules system per official docs.

   What you should see: File tree with `.cursor/rules/team-basics.mdc` saved and open in the editor.

3. Steps 3

   Always Apply rule: what applies to every chat

   In the rule type dropdown (or by editing frontmatter), choose **Always Apply** → `alwaysApply: true`. With `true`, Cursor includes the rule in every Agent session; `globs` and `description` are ignored per the official table.

   Put only norms you truly want **always**: copyright, verification command, forbidden folders, branch conventions. Keep the body short (docs recommend focused rules, ideally under ~500 lines). Avoid pasting entire style guides — point at the linter or an example file with `@`.

   Useful line: «API changes must update `src/types/api.ts` or explain why not.»

   What you should see: In Customize → Rules, the rule shows as Always, or frontmatter has `alwaysApply: true`.

4. Steps 4

   File-scoped rule: `globs` (Auto Attached)

   Create a second file, e.g. `frontend-react.mdc`, for front-end-only norms:

   ```md --- globs: src/components/**/*.tsx alwaysApply: false ---

   - Use named exports in new components. - Co-locate styles in the module CSS next to the component. ```

   With `alwaysApply: false` and `globs` set, the rule **attaches when a matching file is in context** (files you @-mention or the agent opens, per documentation). Separate multiple patterns with **commas**, e.g. `docs/**/*.md, docs/**/*.mdx`.

   Make sure patterns match real paths (`src/**` vs `frontend/**`). A non-matching glob is the top reason «this rule never runs».

   What you should see: Second `.mdc` with `globs:` matching your components folder and `alwaysApply: false`.

5. Steps 5

   Apply Intelligently and Manual: description and @

   Third file: rules you do not want always or tied to a glob.

   **Apply Intelligently (Agent Requested):** `alwaysApply: false`, filled `description`, no `globs`. The agent reads the description and may include the rule when the topic fits (e.g. `description: SQL migrations and rollback; use when editing db/migrations`).

   **Manual:** `alwaysApply: false` with no `description` and no `globs`. It applies only when you mention it in chat, e.g. `@release-checklist.mdc` or picking the rule from the @ menu.

   You can link templates in the body with `@migration-template.sql` so the agent loads a reference file without copying it into the rule (documented at https://cursor.com/docs/rules).

   What you should see: At least one `.mdc` with only `description` and another meant to invoke with @ for occasional tasks.

6. Steps 6

   Test in Agent that the rule is active

   Open **Agent** (not just Tab inline — User Rules do not apply to Cmd/Ctrl+K per the official FAQ). Run three quick checks:

   1. **Always:** ask «which test command should I run before finishing?» — it should cite your global rule without you retyping it. 2. **Globs:** @-mention a `.tsx` file under your pattern and ask for a new component — it should respect named exports if you defined them. 3. **Manual:** type `@team-basics.mdc` or your checklist and request a scoped change.

   If the answer ignores the rule, open Customize → Rules and confirm type and frontmatter. Retry in a fresh message after saving.

   What you should see: Agent replies aligned with your `.mdc` bullets, not generic advice that contradicts the rule.

7. Steps 7

   Commit, review in a PR and drop duplicate legacy

   Add `.cursor/rules/` to git (`git add .cursor/rules`). In the commit message, note which type each file uses (Always vs globs vs manual). If you migrated from `.cursorrules`, **delete** the legacy file in the same PR so instructions are not duplicated.

   In the PR description, link https://cursor.com/docs/rules for onboarding. Ask a teammate to open the repo in Cursor and confirm rules appear in Customize after pull.

   Optional: a short root `AGENTS.md` can coexist for teams that prefer one doc, but do not repeat the same paragraph in five places. When you delegate work to Cloud Agent, versioned rules in the repo are what the VM clones — consistent with cursor-cloud-agent-primer-pr.

   What you should see: `git status` with `.cursor/rules/*.mdc` staged, no `.cursorrules` if you migrated, and Customize showing the same rules on another machine after pull.