How to Add and Structure Cursor Rules (With a File Tree and Co-Author Example)

Cursor does not remember your preferences between chats. Rules are how you put the same instructions back into every Agent session: where files live, what “done” means, and what the model must never do.

This guide covers where rules belong, how to structure them, a file tree you can copy, and a concrete project rule that blocks Cursor co-author trailers in commits and pull requests. Details match Cursor’s rules docs as of October 2026.

What rules are for

A rule is persistent guidance for Agent. When it applies, Cursor includes it at the start of the model context. That is useful for conventions you would otherwise paste into every prompt: WordPress escaping, brand button variants, commit message format, or “never touch production config without asking.”

Rules do not change Tab completions or Inline Edit. They apply to Agent (Chat). If you only need a one-off preference for yourself, a User rule in Settings is enough. If the whole team should share the same rule, put it in the repository.

• Encode project knowledge the model will not invent from the code alone.
• Stop the same mistake from repeating across chats.
• Share standards through git instead of chat folklore.
• Scope guidance so PHP rules do not fire on every CSS edit.

Where to place Cursor rules

Cursor supports several layers. Pick the layer that matches who should see the rule and how long it should live.

Project rules: .cursor/rules/

This is the default for a real codebase. Each rule is an .mdc file under .cursor/rules/, committed with the repo. Use YAML frontmatter to control when it applies. A plain .md file in that folder is ignored. If you want plain markdown, use AGENTS.md instead.

AGENTS.md (and nested copies)

A simple markdown file at the project root, or in a subdirectory. No frontmatter. Nested files combine with parents, and the more specific file wins for that tree. Good for portable instructions that other tools can also read. Prefer .cursor/rules/*.mdc when you need globs or Always Apply.

User rules

Global preferences in Customize → Rules on your Cursor account. They follow you across projects. Keep them for tone, language, and personal habits. Do not put repo-specific secrets or product rules here if the team needs the same behavior.

Team rules

On Team and Enterprise plans, admins manage rules from the Cursor dashboard. They can be enforced so members cannot turn them off. Precedence is Team → Project → User when guidance conflicts.

Legacy .cursorrules

A single .cursorrules file in the project root is legacy and will be deprecated. Migrate its content into a project rule with Always Apply, then remove the old file.

File tree guide

Keep project rules flat under .cursor/rules/ unless the repo is huge. Nested folders work, but descriptive filenames are easier to scan. A practical layout:

your-project/
├── AGENTS.md                      # Optional: short, portable instructions
├── .cursor/
│   └── rules/
│       ├── no-cursor-coauthor.mdc # Always Apply: commit / PR hygiene
│       ├── wordpress-php.mdc      # Globs: **/*.php
│       ├── brandbook-buttons.mdc  # Globs: **/*.{scss,css,tsx}
│       └── api-conventions.mdc    # Apply Intelligently via description
├── src/
├── tests/
└── README.md

What belongs where:

• .cursor/rules/*.mdc — Project standards with clear apply rules. Commit these.
• AGENTS.md — Short overview that other agents can read. Avoid duplicating every .mdc file here.
• User rules — Your personal defaults across all repos.
• Team rules — Org-wide policy from the dashboard, not files in git.

How to structure a rule file

Every project rule is markdown with frontmatter. The three fields that matter are description, globs, and alwaysApply.

Rule type	Frontmatter	When it runs
Always Apply	alwaysApply: true	Every Agent chat in this project
Apply to Specific Files	globs: **/*.php, alwaysApply: false	When matching files are in context
Apply Intelligently	description: …, no globs, alwaysApply: false	When Agent decides the description fits
Apply Manually	No description, no globs, alwaysApply: false	Only when you @-mention the rule

Skeleton:

---
description: Short line for the rule picker and intelligent apply
globs: **/*.{php,js}
alwaysApply: false
---

# Clear title

- Write instructions as commands, not vibes.
- Prefer one concern per file.
- Add a short example of wrong vs right when the cost of failure is high.

Writing tips that keep rules useful

• One concern per file. Split “PHP” and “commits” instead of one giant policy document.
• Be concrete. “Never add Co-authored-by: Cursor” beats “be careful with commits.”
• Use Always Apply sparingly. Reserve it for hygiene that must never be skipped.
• Use globs for stack-specific rules so they stay out of unrelated chats.
• Reference files with @path/to/file instead of pasting whole style guides.
• Update the rule when Agent makes the same mistake twice.

How to add a rule

1. Decide the layer: project .mdc, root AGENTS.md, user setting, or team dashboard.
2. In Agent, run /create-rule and describe the behavior, or open Customize → Rules → Add Rule.
3. Set the apply type. Hygiene rules that must always run use Always Apply.
4. Save under .cursor/rules/ with an .mdc extension and a descriptive name.
5. Commit the file so the team gets the same behavior.
6. Test it: start a new Agent chat and ask for a commit message or a PR body. Confirm the forbidden pattern does not appear.

Concrete example: block Cursor co-author trailers

Cursor (or a hook) can append a trailer such as Co-authored-by: Cursor <cursoragent@cursor.com> to commits or PR text. Many teams do not want AI attribution in git history. Put that in an Always Apply project rule so Agent cannot “helpfully” add it back.

Create .cursor/rules/no-cursor-coauthor.mdc:

---
description: Never add Cursor Co-authored-by trailers to commits or PRs
alwaysApply: true
---

# No Cursor Co-Author Trailers

Never add this line (or any variant) to commit messages, PR titles, or PR descriptions:

Co-authored-by: Cursor <cursoragent@cursor.com>

Also never add:

- Co-authored-by: Cursor
- Any trailer containing cursoragent@cursor.com

## Commit / PR rules

- Write commit messages and PR bodies without AI co-author trailers.
- If a commit hook or tool inserts a Cursor co-author trailer, remove it before finishing.
- Prefer git commit-tree (or equivalent) when amending or rewriting if a hook keeps re-adding the trailer.
- Do not add Cursor attribution in PR descriptions either.

Why this shape works

• Always Apply — Commit and PR wording can show up in any chat, not only when a .git file is open.
• Exact forbidden string — The model has a clear pattern to strip, not a vague “avoid AI credit.”
• Recovery step — Hooks that re-insert the trailer are called out, so Agent knows to remove it again before finishing.
• Covers PRs — Titles and descriptions are included, not only git commit.

“A rule that only says ‘write good commits’ will not stop a trailer. Name the string you refuse to ship.”

How to verify it

1. Commit no-cursor-coauthor.mdc.
2. Open a fresh Agent chat in the same repo.
3. Ask: “Create a commit for the staged changes” or “Draft a PR description.”
4. Confirm the message has no Co-authored-by: Cursor line and no cursoragent@cursor.com address.
5. If a hook adds the trailer after Agent runs, tell Agent to strip it and finish again. Update the rule if that keeps happening.

A small set to start with

You do not need twenty rules on day one. Three is enough for most WordPress or product repos:

• Always Apply — Commit and PR hygiene (the co-author example above).
• Glob-scoped — Language or framework rules for **/*.php, **/*.{scss,css}, and so on.
• Intelligent or manual — Rare workflows: release checklists, migration templates, docs tone.

Add a new file only when you see the same Agent mistake more than once. Rules that document every edge case get ignored by humans and diluted for the model.

Questions developers ask

Why is my rule ignored?

Common causes: the file is .md instead of .mdc, Always Apply is off and the globs do not match files in context, or Apply Intelligently has no useful description. Check Customize → Rules for status, then start a new chat after fixing the file.

Should I use AGENTS.md or .cursor/rules?

Use .cursor/rules when you need Always Apply, globs, or manual @ rules. Use AGENTS.md for a short portable brief. Many teams keep both: a thin AGENTS.md plus focused .mdc files.

Do User rules override project rules?

No. Applicable rules are merged. When they conflict, Team rules win, then Project rules, then User rules. Put team-critical policy in Team or Project rules, not only in your personal settings.

Final words

Put shared standards in .cursor/rules/*.mdc, keep each file to one job, and use Always Apply only for rules that must never slip. The co-author trailer rule is a good first Always Apply file: short, exact, and easy to test on the next commit.

Start with that file tree, add one stack-specific glob rule when Agent repeats a mistake, and grow from there. No giant policy doc. No mystery about where the instruction lives.