Rules & Configuration

Making Cursor Permanently Smarter

🔄 In Lesson 5, you learned Agent mode — powerful but amnesiac. Every new conversation starts fresh. The Agent doesn’t remember that you prefer functional components, hate semicolons, or always use Tailwind CSS.

Rules and configuration fix this. They’re the persistent context layer — instructions that apply to every AI interaction in your project, without you repeating them.

Rules Files: Your Project’s AI Playbook

Rules tell Cursor how to behave in your project. They’re text files that the AI reads before every interaction.

The Modern Approach: .cursor/rules/

Create a .cursor/rules/ directory in your project root. Each .mdc file handles a specific topic:

.cursor/rules/
├── general.mdc          # Overall project conventions
├── testing.mdc          # How to write tests
├── api-patterns.mdc     # API structure and patterns
└── component-style.mdc  # UI component conventions

Example general.mdc:

# Project Conventions

- Use TypeScript strict mode for all files
- Prefer functional components over class components
- Use named exports, not default exports
- Error messages should be user-friendly, not technical
- Never use console.log in production code — use the logger service
- All API responses follow the { data, error, meta } shape

Example testing.mdc:

# Testing Rules

- Use Vitest, not Jest
- Every new function needs at least one test
- Test file goes next to the source file: foo.ts → foo.test.ts
- Use descriptive test names: "should return 404 when user not found"
- Mock external services, never call real APIs in tests

Legacy Format: .cursorrules

You’ll see references to .cursorrules — a single file at the project root. It still works but is deprecated. If you have one, it’s fine to keep using it. For new projects, use .cursor/rules/*.mdc.

Best Practices for Rules

Keep rules under 500 lines total. The AI has limited context. Bloated rules crowd out actual code context.

Include real examples. Don’t just say “follow RESTful patterns.” Show a complete example of a well-structured endpoint. The AI mimics examples better than it follows abstract instructions.

Add rules incrementally. Start with an empty rules directory. When the AI makes the same mistake twice — wrong import style, wrong test framework, wrong error handling — add a rule for it. Don’t try to anticipate everything upfront.

Share with your team. Commit .cursor/rules/ to your repo. Now every team member gets consistent AI behavior.

✅ Quick Check: Your team has a rule that says “Use Tailwind CSS classes, never write custom CSS.” But you just asked Cursor to style a component and it wrote custom CSS anyway. What’s the most likely problem? The rule file might not be in the right location (.cursor/rules/ directory), or the rules file might have a syntax issue. Check that the .mdc file is properly saved and that Cursor has indexed it (you can see active rules in the Composer panel). Also, rules are guidance, not hard constraints — being more specific in the rule (“Always use Tailwind utility classes like className=‘flex items-center gap-2’”) gives better results.

Global Rules

Some preferences apply to all your projects, not just one. Set these in Settings > General > Rules for AI.

Good global rules:

“Always use English for code comments”
“Prefer concise code over verbose code”
“Explain your reasoning when making non-obvious choices”

Global rules combine with project rules. Project rules override global rules when they conflict.

Notepads: Reusable Context Bundles

Notepads live in the AI sidebar. They’re saved blocks of text that can contain @ references, instructions, and code examples.

When Notepads shine:

Recurring code reviews: Create a Notepad with your review checklist and standards. Reference it whenever you ask Cursor to review code
Component generation: A Notepad with your design system’s component patterns, referenced when creating new components
API documentation: A Notepad describing your API structure, authentication, and response shapes

How to create one:

Open the AI sidebar
Go to the Notepads tab
Create a new Notepad with a descriptive name
Add your content, including @ references

How to use one: In any chat, type the Notepad name (Cursor auto-suggests). All the Notepad’s context gets injected into the conversation.

Key difference from rules: Rules apply automatically to every AI interaction. Notepads apply only when you explicitly reference them. Use rules for “always do this” instructions. Use Notepads for “do this when I ask” context.

Custom Documentation

You can make Cursor aware of documentation for any library, framework, or API:

Go to Settings > Features > Docs
Click “Add new doc”
Paste the URL of the documentation
Cursor crawls and indexes it

Now when you type @Docs in chat, that documentation appears as an option. The AI references the actual docs instead of relying on potentially outdated training data.

Add docs for:

Libraries your project depends on (especially less common ones)
Internal APIs and services your team maintains
Framework documentation for the version you’re actually using

MCP: Connecting External Tools

MCP (Model Context Protocol) is a plugin system that extends Cursor’s Agent with external capabilities.

What MCP enables: Agent can interact with databases, project management tools, design platforms, cloud services — anything with an MCP server.

Configuration: Create .cursor/mcp.json in your project root (project-specific) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": {
        "SUPABASE_URL": "your-project-url",
        "SUPABASE_KEY": "your-key"
      }
    }
  }
}

Now Agent can query your Supabase database, read schema information, and write queries grounded in your actual data structure.

Popular MCP servers: Database connectors (Supabase, PostgreSQL), cloud platforms (AWS, Azure), design tools (Figma), project management (Linear, Jira), and documentation tools (Notion, Google Drive).

✅ Quick Check: You have 20 rules across 4 .mdc files totaling 800 lines. Agent is starting to ignore some of your rules. What’s likely happening? Too many rules. The AI has limited context, and 800 lines of rules leaves less room for actual code context. Cut to the 10-15 most important rules (under 500 lines total). Remove rules the AI already follows naturally, and combine redundant rules. Quality over quantity.

Key Takeaways

Project rules (.cursor/rules/*.mdc) make Cursor automatically follow your coding standards — every interaction, no reminders needed
Keep rules under 500 lines, add incrementally, include real code examples
Notepads are reusable context bundles — reference them when needed, unlike rules which always apply
Custom docs (Settings > Docs) let Cursor reference actual library documentation instead of guessing
MCP servers connect Agent to external tools: databases, APIs, design platforms, project management
Commit .cursor/rules/ to your repo so the whole team gets consistent AI behavior

Up Next

You’ve learned the core Cursor workflow: Tab, Cmd+K, Chat, Agent, and Rules. In Lesson 7, you’ll explore the advanced features that take Cursor from good to exceptional: Background Agents that code while you’re away, BugBot for automated PR review, Memories for persistent project knowledge, and how to choose the right AI model for each task.