Cursor Rules: Hoe schrijf je .cursor/rules bestanden die echt werken

Elke Cursor-gebruiker loopt uiteindelijk tegen dezelfde muur. De AI genereert code die technisch werkt, maar de conventies van uw project negeert — verkeerde importpaden, verouderde patronen, componenten die niets lijken op de rest van uw codebase. Cursor Rules lossen dat op door de AI persistente context te geven over hoe uw project werkt.

Wat zijn Cursor Rules en waarom zijn ze belangrijk?

Cursor Rules zijn Markdown-bestanden die fungeren als een permanent systeemprompt dat vóór elke AI-interactie wordt ingevoegd — chat, automatische aanvulling, codegeneratie, alles. Zie ze als onboardingdocumentatie voor de AI. In plaats van elke sessie dezelfde fouten te corrigeren, schrijft u de instructie één keer en die blijft.

De oude aanpak was één .cursorrules-bestand in de hoofdmap van uw project. Dat werkt nog steeds, maar is verouderd. Het huidige systeem gebruikt een .cursor/rules/-map met afzonderlijke .mdc-bestanden (Markdown Cursor), elk gericht op specifieke situaties. Dit is een veel betere opzet, omdat u niet alles in één gigantisch bestand hoeft te proppen — u verdeelt regels per verantwoordelijkheid, en Cursor laadt alleen de regels die relevant zijn voor wat u op dit moment doet.

Als u hebt gewerkt met context engineering voor AI-tools, is het concept vertrouwd: betere invoercontext levert dramatisch betere uitvoer op. Rules zijn context engineering voor uw hele ontwikkelworkflow.

Uw eerste regelbestand instellen

Maak de .cursor/rules/-map aan in de hoofdmap van uw project:

mkdir -p .cursor/rules

Elke regel is een .mdc-bestand met YAML-frontmatter gevolgd door Markdown-inhoud. Dit is het basisskelet:

---
description: "Wanneer deze regel van toepassing moet zijn"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Uw instructies staan hier in gewone Markdown.

Drie frontmatter-velden regelen alles:

U kunt ook regels maken via Cursor zelf — typ /create-rule in de chat en beschrijf wat u wilt. Maar ze handmatig schrijven geeft u meer controle.

De vier regeltypen uitgelegd

Hoe een regel wordt geactiveerd, hangt af van de frontmatter-configuratie. Er zijn vier modi, en de juiste kiezen is belangrijk voor uw contextvensterbudget.

Altijd toepassen

---
alwaysApply: true
---

Geladen bij elke AI-aanvraag. Gebruik dit spaarzaam — voor projectbrede fundamenten zoals uw tech stack-declaratie of kritieke conventies die overal van toepassing zijn. Elke altijd-actieve regel verbruikt tokens bij elke interactie, ongeacht of ze relevant is.

Automatisch gekoppeld (glob-gebaseerd)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Wordt alleen geactiveerd wanneer u bestanden bewerkt die overeenkomen met de glob-patronen. Dit is het meest gebruikte regeltype. Uw React-componentconventies worden geladen wanneer u in componentbestanden werkt, uw API-patronen wanneer u in route-handlers werkt, uw testregels wanneer u tests schrijft.

Door agent aangevraagd (intelligent)

---
description: "Database migratiepatronen met Drizzle ORM"
alwaysApply: false
---

Geen globs, geen always-apply — alleen een beschrijving. De agent van Cursor leest de beschrijving en beslist of de regel relevant is voor de huidige taak. Als u hem vraagt een migratie te schrijven, laadt hij deze regel. Als u een knop opmaakt, slaat hij hem over. Dit werkt verrassend goed voor regels die niet netjes op bestandspaden zijn te mappen.

Handmatig

---
---

Geen frontmatter-velden ingesteld (of lege frontmatter). Deze regels worden alleen geactiveerd wanneer u ze expliciet vermeldt met @regelnaam in de chat. Goed voor zelden gebruikte maar belangrijke instructies — zoals deployment-checklists of refactoringgidsen die u maar af en toe nodig heeft.

Glob-patronen die echt werken

Globs bepalen welke bestanden automatisch gekoppelde regels activeren. Als ze verkeerd zijn, worden uw regels nooit of overal geactiveerd. Dit werkt:

# Alle TypeScript-bestanden in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Alleen componentbestanden
globs: ["**/components/**/*.tsx"]

# Python-bestanden, exclusief tests
globs: ["**/*.py", "!**/test_*.py"]

# Meerdere specifieke mappen
globs: ["src/api/**", "src/services/**"]

Een paar valkuilen uit de praktijk:

• src/* komt alleen overeen met één mapniveau. U wilt bijna altijd src/**/* voor recursieve matching.
• *.js komt niet overeen met .jsx- of .ts-bestanden. Wees expliciet over extensies.
• Globs moeten een YAML-lijst zijn. De accoladesyntax zoals {src,lib}/**/*.ts kan stilzwijgend mislukken — gebruik liever afzonderlijke lijstitems.
• Het !-voorvoegsel sluit patronen uit, wat handig is voor het negeren van gegenereerde bestanden of legacy code.

Praktische regelvoorbeelden

Hier ontmoeten theorie en praktijk elkaar. Dit zijn regels die u in een project kunt toevoegen en direct betere AI-uitvoer zult zien.

Projectbrede basisregel (Altijd toepassen)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Houd dit onder 30 regels. Het wordt bij elke aanvraag geladen, dus elk woord kost tokens.

React-componentregel (Automatisch gekoppeld)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch directly in the component — no useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Python API-regel (Automatisch gekoppeld)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Go-serviceregel (Automatisch gekoppeld)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## De tokenbelasting beheren

Hier is iets dat de meeste Cursor-gidsen overslaan: elke regel die u schrijft kost tokens. Een project met 20 altijd-actieve regels kan **meer dan 2.000 tokens per aanvraag** verbranden aan alleen instructies — voordat de AI zelfs maar naar uw code kijkt.

Dat is belangrijk omdat de chatcontext van Cursor in de standaardmodus ongeveer 20.000 tokens bedraagt. Als uw regels 25% daarvan opeten, heeft u een kwart van de "denkruimte" van de AI voor uw eigenlijke vraag verloren. U zult merkbaar slechtere uitvoerkwaliteit zien naarmate regels zich opstapelen, vooral in langere gesprekken.

Drie principes houden uw tokenbudget gezond:

**1. Gebruik automatisch gekoppelde en door agent aangevraagde regels consequent.** Alleen uw tech stack-declaratie zou altijd actief moeten zijn. Al het andere moet voorwaardelijk worden geladen. Die React-componentregel? Die hoeft niet in de context te zijn wanneer u SQL-migraties schrijft.

**2. Schrijf bondig, niet omslachtig.** Vervang "Het wordt sterk aanbevolen dat ontwikkelaars TypeScript-interfaces gebruiken in plaats van type-aliassen bij het definiëren van publieke API-contracten" door "Prefer `interface` over `type` for public APIs." De AI heeft geen overtuiging nodig — die heeft instructies nodig.

**3. Pas de Drie-Keer-Regel toe.** Codificeer een patroon pas als regel nadat de AI het drie keer fout heeft gedaan. Als Cursor uw naamconventies al correct afhandelt zonder een regel, sla de regel dan over. Elke onnodige regel is verspilde context.

U kunt het tokengebruik monitoren in de statusbalk onderaan het chatvenster van Cursor. Let op wanneer het de 100% nadert — dat is uw signaal om te snoeien.

## Regels organiseren voor een echt project

Een productieproject heeft doorgaans 5-8 regelbestanden nodig. Hier is een structuur die goed werkt:

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 regels)
  components.mdc      # React/Vue-patronen, glob naar componentmappen
  api.mdc             # Backend-conventies, glob naar API-mappen
  database.mdc        # ORM-patronen, glob naar models/migrations
  testing.mdc         # Testconventies, glob naar testbestanden
  deployment.mdc      # CI/CD-patronen, handmatige trigger
  personal.mdc        # Uw voorkeuren (gitignored)

Commit alles naar versiebeheer behalve personal.mdc. Zo krijgt uw hele team hetzelfde AI-gedrag — dat is het hele punt. Zoals een Cursor-forumgebruiker het verwoordt, betekenen goede regels dat u "meer suggesties direct accepteert, met uitvoer die bij de eerste poging uw conventies volgt."

Als u naast Cursor andere AI-coderingstools gebruikt, zijn de concepten direct overdraagbaar. Claude Code gebruikt CLAUDE.md, GitHub Copilot heeft instructiebestanden, en Windsurf heeft zijn eigen formaat — maar het onderliggende principe is identiek.

Hoe regelprioriteit werkt

Wanneer meerdere regels op hetzelfde bestand van toepassing zijn, volgt Cursor een duidelijke hiërarchie:

Team Rules zijn beschikbaar in Team- en Enterprise-abonnementen. Ze worden ingesteld in het Cursor-dashboard door beheerders en zijn organisatiebreed van kracht — individuele ontwikkelaars kunnen ze niet uitschakelen.

Binnen projectregels is het gedrag niet strikt gedefinieerd als twee regels op hetzelfde bestand van toepassing zijn en conflicteren. In de praktijk hebben later geladen regels de neiging voorrang te krijgen. Door uw bestanden te nummeren (001-base.mdc, 002-components.mdc) krijgt u een voorspelbare volgorde.

Veelgemaakte fouten en hoe u ze kunt verhelpen

Na het doorlezen van tientallen community-threads en het testen van regels in verschillende projecten, zijn dit de fouten die de meeste mensen struikelen:

Regels schrijven die te vaag zijn. "Schrijf schone code" vertelt de AI niets. "Gebruik benoemde exports, geen standaard exports. Structureer componenten als: imports, typen, functie, subcomponenten" geeft iets concreets.

Alles op always-apply zetten. Het eerste instinct is om alwaysApply: true op elke regel te zetten. Weersta dat. Controleer uw regels elk kwartaal — als u meer dan 2-3 altijd-actieve regels heeft, verspilt u waarschijnlijk tokens.

Vergeten regels te testen. Na het schrijven van een regel opent u een relevant bestand en vraagt u Cursor iets te genereren dat de regel zou moeten volgen. Als dat niet gebeurt, kan uw glob-patroon verkeerd zijn, of de instructie niet duidelijk genoeg.

Anti-patronen niet documenteren. De AI vertellen wat ze moet doen is de helft van het werk. Haar vertellen wat ze niet moet doen is de andere helft. Voeg in elke regel een "NOOIT dit doen"-sectie toe met expliciete voorbeelden van de verkeerde aanpak.

Regelopslag in de UI negeren. Een bekende bug zorgt ervoor dat regelwijzigingen verdwijnen. Als wijzigingen verdwijnen, sluit Cursor volledig af, selecteer "Overschrijven" in het pop-up voor niet-opgeslagen wijzigingen en open het opnieuw.

Cursor Rules vs CLAUDE.md vs AGENTS.md

Cursor is niet het enige hulpmiddel dat instructiebestanden gebruikt. Zo vergelijken de formaten voor iedereen die met meerdere AI-codeerassistenten werkt:

Het voordeel van Cursor is granulariteit. CLAUDE.md en AGENTS.md zijn eenvoudiger — ze laden alles altijd. Cursor laat u de juiste regels op het juiste moment laden, wat belangrijk wordt zodra uw instructieset groter wordt dan een paar honderd regels.

Voor een diepgaandere blik op hoe context de AI-uitvoer in deze tools beïnvloedt, behandelt onze context engineering-gids de principes die van toepassing zijn ongeacht welke editor u gebruikt.

FAQ

Is .cursorrules verouderd?

Ja. Het enkele .cursorrules-bestand in de hoofdmap van uw project werkt nog steeds, maar Cursor raadt aan te migreren naar .cursor/rules/*.mdc-bestanden. Het nieuwe formaat ondersteunt glob-patronen, voorwaardelijk laden en betere organisatie. Migreer door uw monolithische bestand op te splitsen in gerichte regels.

Welke bestandsextensie moet ik gebruiken — .mdc of .md?

Gebruik .mdc voor bestanden die YAML-frontmatter bevatten (description, globs, alwaysApply). Gewone .md-bestanden werken ook in de rules-map, maar ondersteunen de frontmatter-metadata niet die voorwaardelijk laden mogelijk maakt.

Hoeveel regels moet een project hebben?

Vijf tot acht is de ideale zone voor de meeste projecten. Één altijd-actieve basisregel, drie tot vier automatisch gekoppelde regels per bestandstype en één of twee handmatige regels voor speciale taken. Meer dan 10 regels betekent doorgaans dat sommige kunnen worden geconsolideerd of verwijderd.

Beïnvloeden Cursor Rules de automatische aanvulling en tab-aanvulling?

Regels zijn van toepassing op chat- en agentinteracties. Gebruikersregels zijn niet van toepassing op inline bewerkingen (Cmd/Ctrl+K), en regels hebben over het algemeen geen invloed op Cursor Tab-aanvullingsuggesties. Ze zijn het meest effectief in chat- en Composer-sessies.

Kan ik regels delen tussen meerdere projecten?

Ja, via de Remote Rules-functie van Cursor. Ga naar Cursor Settings > Rules, Commands, selecteer "Remote Rule (GitHub)" en plak een repository-URL. Regels worden automatisch gesynchroniseerd wanneer de bronrepository wordt bijgewerkt. U kunt ook een gedeelde regelsrepository onderhouden en in elk project linken.

Wat is de aanbevolen maximale regellengte?

De documentatie van Cursor suggereert individuele regels onder 500 regels te houden. In de praktijk streeft u naar onder de 100 regels per regel. Kortere regels zijn gemakkelijker te onderhouden en kosten minder tokens. Als een regel meer dan 150 regels bedraagt, splits die dan op in twee gerichte regels.

Werken regels met alle AI-modellen in Cursor?

Regels werken met elk model dat Cursor ondersteunt — Claude, GPT-4o, Gemini en andere. De regels worden ingevoegd als context op systeemniveau, ongeacht welk model u heeft geselecteerd. Het modelgedrag kan variëren, maar de regels zelf zijn model-agnostisch.

Hoe debug ik een regel die niet werkt?

Controleer eerst of het glob-patroon overeenkomt met uw bestand — open het bestand en kijk of de regel verschijnt in het contextvenster. Test vervolgens met een directe vraag die de regel zou moeten activeren. Probeer daarna tijdelijk alwaysApply: true in te stellen om te bevestigen dat de regelinhoud zelf werkt. Als dat zo is, zit het probleem in uw glob-patroon.

Moet ik .cursor/rules in git committen?

Absoluut. Het hele punt van projectregels is teamwijde consistentie. Commit alles in .cursor/rules/ behalve persoonlijke voorkeurbestanden. Voeg personal.mdc toe aan .gitignore voor individuele instellingen die niet voor iedereen gelden.

Kan ik Cursor Rules gebruiken naast MCP-servers?

Ja, en ze vullen elkaar goed aan. Regels definiëren hoe de AI code moet schrijven, terwijl MCP-servers de AI toegang geven tot externe tools en gegevens. Een regel kan zeggen "gebruik altijd onze interne API-client", terwijl een MCP-server de AI in staat stelt die API daadwerkelijk te bevragen tijdens de ontwikkeling.

Staan er AI-functies op je roadmap? Dat is onze specialiteit: het AI-integratieteam van Techsy brengt LLM-systemen van prototype naar productie. Wil je een second opinion over je stack? Vraag een gratis adviesgesprek aan.

Bronnen

• Cursor Rules Documentation
• Trigger.dev — How to Write Great Cursor Rules
• Cursor Forum — MDC Rules Best Practices and Troubleshooting
• Peakvance — Guide to Cursor Rules: Token Tax
• awesome-cursor-rules-mdc on GitHub