Draft, pending test: written from current vendor docs. We have not run this workflow end to end yet, so nothing below is a measured result. Not indexed.

Cursor rules: a .cursor/rules setup that keeps the agent consistent in your repo

Create .cursor/rules/ in your repo with a few short .mdc rule files: one always-applied core rule (stack, commands, conventions), scoped rules attached to file globs (e.g. **/*.tsx for UI conventions), and agent-requested rules for rare tasks like migrations. Keep each rule short and concrete, commit them, and test with a prompt that would break a rule if it weren't loaded.

Who it's for & level

Developers and vibe coders who use Cursor's agent every day and are tired of re-explaining the stack, the test command and 'don't touch that folder' in every chat. Teams that want the agent to behave the same for everyone.

Level
intermediate
Tools
Cursor
Roles
Developers Vibe coding
Goals
Ship an app
Tasks
Workflow automation
Time to set up
30–60 min for a first set of rules plus checks (est.)
Cost
Included in your Cursor plan. Always-on rules add tokens to every request, so keep them short.
Time saved
Several minutes per agent session no longer spent restating context or fixing convention drift (est.) (est.)
Test status
Pending test
Last verified
pending test
Model versions
n/a
Written by
Usecased editorial (pending test) (agent)
Published
2026-10-15

Prerequisites

The problem

The agent forgets your stack, uses the wrong package manager, writes tests in the wrong framework and edits generated files. A single giant rules file gets ignored or eats context. You need a small set of rules that load when relevant and that you can verify are working.

Steps

  1. Collect what you keep repeating. Scan your recent agent chats for corrections you typed more than twice: package manager, test command, folder boundaries, naming, error handling. These are your first rules.
  2. Create the core rule. Add .cursor/rules/core.mdc with alwaysApply: true. Keep it to the stack, commands and hard boundaries, ideally under 40 lines.
  3. Add scoped rules. Create rules with globs for areas with their own conventions (UI components, API routes, tests). They attach only when matching files are in context.
  4. Add on-demand rules. For rare tasks (DB migrations, release steps) write rules with a clear description and no globs, so the agent can pull them in when the task matches, or you can @-mention them.
  5. Test that rules load. Run the check prompts below in a fresh chat. If the agent picks the wrong package manager or test framework, the rule isn't loading or isn't clear enough.
  6. Commit and maintain. Commit .cursor/rules/. When you correct the agent twice for the same thing, update a rule instead. Delete rules that no longer match the codebase.

Exact prompt & config

1. .cursor/rules/core.mdc · Frontmatter keys as documented by Cursor at the time of writing; check the Rules docs for your version.
---
description: Core project conventions
alwaysApply: true
---
- Stack: Astro 5 + TypeScript, deployed on Cloudflare Workers.
- Package manager: npm. Never use yarn or pnpm.
- Run checks with `npm test` and `npm run build` before saying a task is done.
- Never edit files in dist/ or src/generated/.
- Ask before adding a dependency.
2. .cursor/rules/ui-components.mdc (scoped)
---
description: UI component conventions
globs: src/components/**/*.astro
alwaysApply: false
---
- One component per file, PascalCase file names.
- Props typed with an exported `Props` interface.
- No inline styles; use the classes in src/styles/.
- Every interactive element needs an accessible name.
3. .cursor/rules/db-migrations.mdc (on demand)
---
description: Use when creating or changing D1 database migrations
alwaysApply: false
---
- New migration = new numbered file in migrations/ (never edit an applied one).
- Test locally with `npm run db:migrate:local` first.
- Never run remote migrations; tell me the command instead.
4. Check prompts (fresh chat each)
a) "Add the date-fns package and use it in src/lib/seo.ts."   → expect: asks before adding, uses npm
b) "Create a Button component."                               → expect: PascalCase file, Props interface
c) "Add a column 'source' to the page_changes table."         → expect: new migration file, no remote run

Sample output

Example output, written to show the expected shape. Not captured from a real run yet.

(Example of the expected shape, not a captured run)

Check a) Agent: "Adding a dependency needs your OK per project rules. Proceed with `npm install date-fns`?"  PASS
Check b) Created src/components/Button.astro with `export interface Props`.                          PASS
Check c) Created migrations/0005_page_changes_source.sql; suggested running db:migrate:local.          PASS

Why several small rules

One giant rules file is either always loaded (expensive and diluted) or ignored. Splitting by when a rule matters (always, for these files, for this task) keeps the context small and the instructions relevant.

The loop that keeps you in control

  1. Collect repeated corrections.
  2. Write short rules by scope.
  3. Check with prompts designed to break them.
  4. Update a rule whenever you correct the agent twice.

Going further

Connect tools the rules can reference, like Playwright via our Cursor MCP setup case, and add a rule that says ‘after UI changes, run the signup walkthrough’ from our Playwright MCP case.

How it went

Pending test. What we expect, based on the vendor docs and public reports below. This becomes a measured result after our run.

Expected result, pending our test: the always-on rule should be followed consistently, scoped rules when matching files are in context, and on-demand rules less reliably unless mentioned. We'll record which checks passed on a fresh chat, which rule types needed rewording, and the context cost of the always-on rule.

Worth knowing

FAQ

What are Cursor rules?

Instructions stored in your project (.cursor/rules/) or user settings that Cursor adds to the agent's context, so it follows your stack and conventions without being told each time.

What's the difference between .cursorrules and .cursor/rules?

.cursorrules is the legacy single file. .cursor/rules/ holds multiple rule files that can be always-on, scoped by file pattern or pulled in on demand.

How long should a Cursor rule be?

Short. A few concrete bullets per rule; split by area rather than writing one long file.

How do I know a rule is working?

Run a prompt in a fresh chat that would break the rule if it weren't loaded, and see whether the agent follows it.

Related use cases