.cursorrules patterns from real engineers: what actually moves the needle

The .cursorrules file (or the newer .cursor/rules/*.mdc system) is the single highest-leverage configuration in a Cursor workflow. Most engineers spend ten minutes on theirs and then never revisit. After collecting .cursorrules files from a dozen working engineers and iterating on my own through three projects, here are the patterns that actually move the needle.

What .cursorrules is for

A .cursorrules file at the root of your project gets prepended to every prompt Cursor sends to the model. It’s your “always-on system message.” Used well, it’s the cheapest way to make Cursor stop doing the things that annoy you.

Used badly, it’s where engineers paste vague aspirational guidelines that the model ignores.

The rules that matter, in priority order

1. The “don’t explain, just output” rule

Never explain code unless I ask. Just output the code block.

This single line saves thousands of output tokens per day for users on the new Cursor pricing. The 328-upvote r/cursor workflow thread names this specifically as the highest-impact rule for power users.

Trade-off: you lose the “here’s what I changed” context. If you need that occasionally, ask in the moment with “explain this diff.”

2. The stack rule

This project uses: TypeScript strict mode, Astro 5, Tailwind 4 (NOT 3), Cloudflare Workers runtime (NOT Node). When generating code, ONLY use APIs available in these.

The model otherwise defaults to “Node, Tailwind 3” code, especially for less-mainstream stacks. Explicitly naming the stack prevents this.

3. The “ask before” rule

Ask before:
- Adding new dependencies
- Editing wrangler.jsonc / package.json / tsconfig.json
- Creating new top-level directories
- Changing the build pipeline

This stops the model from making “improvements” you didn’t ask for. The model defaults to helpful-but-overreaching; this rule reins it in.

4. The “do not” rule

Never:
- Add comments unless the why is non-obvious
- Use console.log in committed code (use a logger if logging is needed)
- Mock external services in unit tests; use real-ish test data
- Touch the `dist/` directory

Anti-patterns are more specific than principles. Naming what you don’t want is more effective than naming what you do.

5. The naming convention rule

Naming:
- Functions: verb-noun (loadUser, not getUser)
- Types: PascalCase nouns (UserSession, not user_session)
- Variables: camelCase, descriptive (userInput, not input)
- Constants: SCREAMING_SNAKE_CASE
- Files: kebab-case (user-session.ts)

The model has its own defaults. Spelling out yours stops the drift.

6. The architecture pointers

Where things live:
- Server-only logic: src/server/
- Astro components: src/components/
- Page routes: src/pages/
- Content (MDX): src/content/<collection>/
- Shared types: src/lib/types.ts
- Tests: alongside source as *.test.ts

The model otherwise guesses, which means new files end up in inconsistent places.

What NOT to put in .cursorrules

A few patterns that look helpful but mostly aren’t:

“Write clean, maintainable code”: vague aspirations don’t change model behaviour. Specific rules do.

Long philosophical preambles: the model has limited attention budget for the rules file. Wasted tokens.

Project history / “in 2024 we decided X”: stale fast, eats context, rarely useful.

Per-team-member preferences: if multiple developers share the project, keep .cursorrules shared and put personal preferences in your local Cursor settings.

“Refer to the documentation at docs/…”: the model can’t actually read external files at rules-evaluation time. If the doc is important, paste the relevant section into the rules file.

The plan-mode interaction

Cursor’s Plan Mode (covered in the 437-upvote Reddit thread) interacts with rules in useful ways:

• Plan Mode lets you confirm the plan before edits happen
• .cursorrules constraints apply to both the plan and execution
• A good rule: “Before executing changes that touch more than 3 files, present a plan first.” Forces deliberate pacing on multi-file work.

A real .cursorrules example

What mine actually looks like for TopInsight:

# TopInsight project rules

## Style
- Never explain code unless I ask
- TypeScript strict mode, no `any` without explicit comment why
- Single quotes, no semicolons trailing comma
- Use U+2019 (curly apostrophe) in user-facing prose, not ASCII '

## Stack
- Astro 5, NOT Next.js
- Tailwind 4 (with `@theme` directive, NOT Tailwind 3 config)
- Cloudflare Workers runtime, NOT Node
- MDX for content

## Architecture
- Components in src/components/, lowercase filename, .astro
- Layouts in src/layouts/
- Content in src/content/<collection>/ with frontmatter + body
- Static assets in apps/web/public/

## Conventions
- Function names: verb-noun (loadUser, not getUser)
- File names: kebab-case
- No console.log in committed code

## Ask before
- Adding dependencies
- Editing wrangler.jsonc, package.json, tsconfig
- Creating new src/ subdirectories
- Touching src/content/authors/charles-lin.md

About 40 lines. Specific. Project-aware. Updated maybe once a month as I notice new drift.

The maintenance discipline

The single most-skipped step: updating .cursorrules when you notice the model doing something annoying repeatedly. Each correction you’ve made twice → add it to the rules. Over a few months you converge on a file that meaningfully changes the model’s default behaviour.

The rule itself: every time you correct the AI on the same kind of thing twice, that’s evidence you should add it to .cursorrules.

For broader Cursor workflow context, see our Cursor review and Cursor vs Copilot piece. For the Aider equivalent (.aider/CONVENTIONS.md), see Aider best practices.