Give Cursor standing instructions with project rules

Every time you start a new chat in Cursor, the AI knows nothing about your project except what it can read. So you end up repeating yourself: "we use TypeScript", "tests go next to the code", "don't add new dependencies without asking".

Rules fix that. A rule is a short instruction file that Cursor includes in the AI's context, either every time or when it's relevant. You write it once and stop repeating yourself.

This recipe sets up a small, useful set of rules. It assumes you have Cursor installed and a project open. If you've used Claude Code, rules are Cursor's equivalent of CLAUDE.md.

The four places instructions can live

Cursor's docs describe several kinds of persistent instructions:

According to Cursor, when several apply they're combined in this order: Team Rules, then Project Rules, then User Rules. Most people only need the first, second and fourth.

Step 1: Create your first project rule

The easiest route is to let Cursor create the file so you get the current format:

1. Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows and Linux).
2. Run New Cursor Rule.
3. Give it a name, such as project-basics.

Cursor creates the rule inside .cursor/rules in your project. You can also reach rules from Cursor Settings, in the Rules section.

Cursor's rule format has changed over time. The long-standing format is a .mdc file in .cursor/rules (a Markdown file with a settings block at the top). Some newer versions may generate a folder per rule instead. Whichever you get, keep the shape Cursor generates for you and edit the contents rather than renaming things by hand. A plain .md file dropped into the folder has no settings block, so Cursor's docs say it is ignored.

Step 2: Understand the settings block

At the top of a rule file, between two --- lines, sit three settings. Together they decide when the rule is used:

---
description: Short explanation of what this rule covers
globs:
alwaysApply: false
---

• alwaysApply: if true, the rule goes into every chat.
• globs: file patterns such as src/**/*.tsx. The rule is pulled in when you're working with matching files.
• description: a plain-English summary. Cursor's agent reads it and decides whether the rule is relevant to the task.

Those combinations give you four behaviours, which Cursor's rule settings show as Always Apply, Apply Intelligently, Apply to Specific Files and Apply Manually:

The labels in Cursor's interface and the underlying settings don't always line up neatly (users on Cursor's forum have noted this), so after you save a rule, check how Cursor describes it in the Rules settings.

Step 3: Write an "always on" rule

Keep this one short. It's included in every chat, so every line costs the AI's attention.

---
description: Core conventions for this project
alwaysApply: true
---

# Project basics

- This is a Next.js app written in TypeScript. Prefer TypeScript over plain JavaScript.
- Tests live next to the file they test, named `*.test.ts`.
- Run `npm test` after changing logic, and fix failures before you finish.
- Don't add new dependencies without asking first.
- Keep changes small. Don't reformat files you aren't otherwise editing.

Swap in your own stack and commands. Put in what you'd tell a new teammate on day one.

Step 4: Write a file-specific rule

Now a rule that only appears when relevant. Say your React components follow a pattern:

---
description: React component conventions
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use function components with named exports.
- Props get an explicit TypeScript type called `<ComponentName>Props`.
- Styling uses the existing CSS modules. Don't add inline styles.

When you work on a file under src/components, Cursor can bring this rule in. Rules for other parts of the code stay out of the way.

Step 5: Write an agent-chosen rule

For guidance that isn't tied to file names, rely on the description. Leave globs empty and write the description so it says when it applies:

---
description: How to add or change database migrations. Use when editing the schema or writing SQL.
alwaysApply: false
---

- Create a new migration file. Never edit one that has already been applied.
- Make every migration reversible.
- Mention the migration in your summary so a human can review it.

A vague description ("database stuff") gives the agent little to go on, so it may skip the rule. Be specific about the trigger.

Step 6: Reference a rule by hand

A rule with no description, no globs and alwaysApply: false only applies when you ask for it. In chat, type @ followed by the rule's name to attach it. This suits things like a release checklist you want on demand.

Step 7: Or just use AGENTS.md

If your project is used with more than one AI tool, you may prefer a single plain file. Cursor reads AGENTS.md in your project root, and in subdirectories. It's ordinary Markdown with no settings block:

# AGENTS.md

## Setup
- Install with `npm install`. Start the dev server with `npm run dev`.

## Conventions
- TypeScript everywhere. Tests sit next to the code.
- Ask before adding dependencies.

The trade-off: AGENTS.md is simple and portable (OpenAI Codex also reads it), but it has none of the "only when relevant" targeting of .cursor/rules. A reasonable setup is a short AGENTS.md for the basics and a few targeted rules for the rest. If you use both, avoid contradicting yourself between them.

Step 8: Add personal preferences as User Rules

User Rules apply across all your projects and are set in Cursor's settings, not in a file in your repo. Use them for taste, not project facts:

• "Explain changes in plain English before showing code."
• "Ask me before running anything that deletes files."

Because they live in settings rather than your project, teammates won't get them. Anything the whole team should follow belongs in Project Rules or AGENTS.md.

Step 9: Test and tune

1. Start a new chat in Agent mode and ask for something your rules cover, such as "add a new component for a pricing card".
2. Check the result against the rules. Did it use the right naming, the right styles?
3. If not, look at which rule should have applied. Was alwaysApply off? Did the glob match the file? Was the description specific?
4. Edit the rule and try again.

A few habits make rules work better:

• Keep each rule focused. Cursor's docs suggest splitting large rules into smaller, composable ones.
• Be concrete. "Use camelCase for functions" beats "write clean code".
• Say what to do, not only what to avoid. Give the preferred alternative.
• Include commands. The exact test and build commands save the AI guessing.
• Treat rules as guidance. The AI usually follows them but it isn't a guarantee, so keep reviewing changes.

Step 10: Commit your rules

Project rules are plain files, so they belong in Git with the rest of your code. Commit .cursor/rules and your teammates get the same instructions. If you're new to Git, see A safety net for AI coding.

Troubleshooting

Cursor ignores my rule. Check that it's in .cursor/rules and has the settings block. Then check why it should apply: is alwaysApply true, does the glob match the file you're working on, or does the description clearly describe the task?

A file I added by hand isn't picked up. A plain .md file without the settings block is ignored. Use New Cursor Rule and paste your content into the file it creates.

The AI feels distracted. You may have too many "always" rules. Move the ones that apply to a few file types into glob rules.

Rules work locally but not in a Cloud Agent. Project rules and AGENTS.md are read from the repository, so they only apply if they're committed. User Rules live in your account settings instead.

Recap

1. Run New Cursor Rule to create a file in .cursor/rules.
2. Use alwaysApply, globs and description to control when it applies.
3. Keep the always-on rule tiny and make the others targeted.
4. Use AGENTS.md if you want one simple file that other tools can read too.
5. Put personal taste in User Rules, and commit project rules to Git.

Once you have rules, the next upgrade is giving Cursor new abilities with an MCP server. If you're choosing between tools, see Cursor vs GitHub Copilot.