how to set up cursor rules: the complete guide

If you’re using Cursor as your AI-powered code editor, you’ve probably noticed it’s pretty smart out of the box. But “pretty smart” isn’t the same as “knows exactly how your team works.” That’s where cursor rules come in — and once you set them up, you’ll wonder how you ever coded without them.

What are cursor rules?

Cursor rules are configuration files that tell Cursor’s AI how to behave in your project. Think of them as a personality and knowledge download for your coding assistant. Instead of repeating “we use TypeScript here” or “always add error handling” in every prompt, you write it once and Cursor remembers.

The rules live in a .cursor/rules directory at the root of your project. Each rule is a markdown file (.mdc) that describes a specific behavior, convention, or piece of context you want the AI to follow.

Why cursor rules matter

Without rules, Cursor’s AI is a generalist. It’ll write code that works, but it won’t match your team’s style. It might suggest React class components when you exclusively use hooks. It might generate JavaScript when your entire codebase is TypeScript. It might skip tests when your team requires them.

Cursor rules fix all of that. They turn a generic assistant into one that genuinely understands your project. Teams that invest a few minutes in cursor configuration report significantly faster code reviews, fewer AI-generated corrections, and less time spent re-prompting.

Setting up .cursor/rules step by step

1. Create the directory

At the root of your project, create the rules folder:

mkdir -p .cursor/rules

2. Create your first rule file

Each rule is a .mdc file inside that directory. Let’s start with a general project rule:

# Project conventions

- We use TypeScript exclusively — never plain JavaScript
- All components are functional with React hooks
- Use named exports, not default exports
- Error handling is required for all async operations
- Write unit tests for all utility functions

Save this as .cursor/rules/conventions.mdc.

3. Add context-specific rules

The real power comes from layering rules. Create separate files for different concerns:

.cursor/rules/style.mdc — coding style and formatting:

# Code style

- Use 2-space indentation
- Prefer const over let, never use var
- Use template literals instead of string concatenation
- Destructure props in function parameters

.cursor/rules/architecture.mdc — project structure:

# Architecture

- Components go in src/components/
- Shared hooks go in src/hooks/
- API calls are centralized in src/api/
- Use the repository pattern for data access

.cursor/rules/testing.mdc — testing expectations:

# Testing

- Use Vitest for unit tests
- Use Playwright for e2e tests
- Test files live next to the code they test
- Aim for testing behavior, not implementation details

4. Commit your rules

This is important — .cursor/rules should be committed to your repo. This way, everyone on the team gets the same AI behavior. Add it to version control just like any other config file:

git add .cursor/rules/
git commit -m "add cursor rules for AI consistency"

Best practices for writing cursor rules

Be specific, not vague. “Write good code” doesn’t help anyone. “Use early returns to reduce nesting” gives the AI something concrete to follow.

Keep rules modular. One file per concern makes rules easier to update and reason about. Don’t dump everything into a single massive file.

Include examples when helpful. If you have a particular pattern you want followed, show a short code snippet. The AI learns faster from examples than from abstract descriptions.

Update rules as your project evolves. Rules aren’t a “set it and forget it” thing. When your team adopts a new convention, add it to the rules. When something becomes outdated, remove it.

Don’t over-constrain. You want guidance, not a straitjacket. Leave room for the AI to be helpful in unexpected ways.

The easier way: use spaget

Setting up cursor rules manually works great — but it gets tricky when you want to maintain configurations across multiple projects or export to other AI tools too.

That’s exactly what spaget was built for. Instead of hand-writing .mdc files, you design your agent’s behavior visually. Drag in skills, define conventions, set the personality — then export directly to .cursor/rules format with one click.

The best part? If you also use Claude Code or GitHub Copilot, spaget exports to those formats too. One agent configuration, every platform. No reformatting, no copy-pasting between different config syntaxes.

No account required. Just open app.spaget.ai and start building.

Wrapping up

Cursor rules are one of the highest-leverage things you can do to improve your AI coding experience. A few minutes of setup saves hours of re-prompting and correcting. Start with your most important conventions, iterate as you go, and consider using spaget if you want a faster, more visual workflow.

Your AI assistant is only as good as the instructions you give it. Make them count.