Cursor-regels: hoe je AI in lijn houdt met je codebase

Je opent een nieuwe chat in Cursor en plakt hetzelfde blok instructies dat je al honderd keer hebt geplakt. Je stack, je naamgevingsconventies en de mapstructuur die de AI steeds fout doet. Vervolgens genereert hij een klasse van 40 regels met drie abstractielagen voor iets dat gewoon een functie nodig had.

Tijd om uit deze nachtmerrie te ontwaken. Cursor-regels zijn projectbestanden die plakken overbodig maken. Schrijf je conventies één keer op, en de output van de AI sluit aan op je codebase in plaats van ertegenin te gaan.

Deze tutorial bouwt een set .mdc-regelbestanden voor een Python-webproject met FastAPI en pytest, met onder meer projectcontext, code-eenvoud en API-foutopmaak. Als je nieuw bent met Cursor, raad ik aan eerst onze cursus Software Development with Cursor te volgen, open daarna een project en doe mee.

Wat zijn Cursor-regels?

Cursor-regels zijn markdown-bestanden met MDC-specifieke frontmatter die in je project staan op .cursor/rules/. Voordat je prompt het model bereikt, controleert Cursor welke regels matchen en plaatst hun inhoud vooraan in het contextvenster. Jouw instructies komen elke keer eerst.

Elk .mdc-bestand heeft drie frontmatter-velden die de activatie bepalen: description, globs en alwaysApply. Een regel kan bij elk gesprek afgaan of alleen wanneer bepaalde bestanden open zijn. Een derde optie, Apply Intelligently, laat de agent de beschrijving lezen en zelf bepalen of de regel relevant is. In de volgende sectie behandelen we elk type hands-on.

Cursor ondersteunt vier categorieën regels:

Projectregels vervingen het oudere .cursorrules-bestand, één enkel root-bestand zonder scoping of metadata, door regels op te splitsen in meerdere .mdc-bestanden met frontmatter.

AGENTS.md is het eenvoudigere alternatief voor projecten die geen glob-scoping nodig hebben. Het is gewone markdown die wordt herkend door AI-codetools buiten Cursor, en diepere bestanden in submappen overschrijven bovenliggende.

Je kunt meer leren over hoe agent-gebaseerde workflows aansluiten op je ontwikkelproces in onze skill track AI Agent Fundamentals.

Cursor-projectregels maken en configureren

De rest van deze tutorial bouwt regelbestanden voor een FastAPI-project met pytest. De patronen zijn toepasbaar op elke stack.

De map rules en bestanden opzetten

Maak een .cursor/rules/-map in de root van je project. Elk .mdc-bestand dat je hier plaatst wordt een regel die Cursor direct oppakt, zonder herstart.

Het eerste regelbestand, project-context.mdc, geeft de AI een blijvend besef van je stack en mapindeling:

---
description: ""
alwaysApply: true
globs:
---
 
# Project Context
 
This is a FastAPI web application with pytest for testing.
 
## Tech Stack
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
- pytest with pytest-asyncio for async test support
- Alembic for database migrations
 
## Project Structure
- app/main.py: FastAPI application entry point
- app/routers/: API route handlers
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic request/response schemas
- tests/: pytest test files mirroring app/ structure
 
## Patterns
- All endpoints are async
- Use dependency injection for database sessions
- Response models are always Pydantic schemas, not raw dicts

Door /create-rule te typen in een Agent-chat kan het ook: Cursor maakt er via een chatpaneel eentje voor je op.

De frontmatter alwaysApply: true betekent dat deze regel in elk gesprek wordt geladen. Geef bestanden een kebab-case naam per onderwerp (project-context.mdc, simplicity.mdc, error-responses.mdc) en houd elk onder 500 regels. Een opgeblazen regelbestand vreet ruimte in het contextvenster die je nodig hebt voor je echte code en prompts. Commit de map .cursor/rules/ naar git.

Regelmetadata configureren voor accurate matching

De regel project-context.mdc hierboven gebruikt alwaysApply: true, de simpelste modus: elk gesprek laadt hem ongeacht aan welke bestanden je werkt. Dat is de juiste keuze voor projectbrede context.

Sommige regels gelden alleen voor bepaalde delen van de codebase. Zet alwaysApply: false en voeg glob-patronen toe als door komma’s gescheiden lijst om ze te scopen. Een regel met globs: app/routers/**/*.py gaat alleen af wanneer matchende bestanden (hier: Python-bestanden in app/routers/ of submappen) in context verschijnen, zodat API-conventies uit niet-gerelateerde chats blijven.

Apply Intelligently slaat bestands­patronen helemaal over. Je laat globs leeg en schrijft in plaats daarvan een gedetailleerde description, en de agent beslist of de regel relevant is voor het huidige gesprek. De kwaliteit van de beschrijving is belangrijk: "Error handling rules" is te vaag om betrouwbaar te matchen, maar "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" heeft duidelijke signalen.

Regels zonder globs, zonder betekenisvolle beschrijving en met alwaysApply: false worden alleen handmatig geladen wanneer je @rule-name typt in de chat. Handig voor naslag die je op aanvraag inlaadt.

Regelinhoud en randvoorwaarden schrijven

Regels met zachte bewoording ("probeer functies klein te houden", "prefereer async endpoints") geven de AI toestemming om ze te negeren. Schrijf opdrachten: "Functies moeten onder de 30 regels blijven. Alle endpoints moeten async zijn."

In de intro noemden we dat de AI een klasse van 40 regels met drie abstractielagen genereerde. De regel die dat gedrag stopt is simplicity.mdc:

---
description: ""
alwaysApply: true
globs:
---
 
# Code Simplicity
 
Write the simplest code that solves the problem. Every abstraction must earn its place.
 
## Constraints
- No base classes with one child class
- No interfaces or abstract classes with one implementation
- No factory or strategy patterns when an if statement works
- No wrapper functions that just call another function
- No configurable parameters that nothing passes
- No "just in case" error handling for impossible conditions
 
## When modifying existing code
- Match the patterns already in the codebase
- Do not refactor surrounding code unless asked
- Do not add type annotations to unchanged code
- Do not add docstrings to unchanged functions
 
## Code size
- Functions under 30 lines
- If a function needs a comment explaining what a block does, extract that block into a named function instead

Het verschil is direct merkbaar. De AI grijpt niet meer naar abstracte basisklassen wanneer er maar één implementatie is, en gebruikt if-statements wanneer er twee gevallen zijn.

De derde regel, error-responses.mdc, is met globs gescoped zodat hij alleen afgaat wanneer je aan API-routebestanden werkt:

---
description: "Standard error response format for all API endpoints"
alwaysApply: false
globs: app/routers/**/*.py
---
 
# API Error Responses
 
All error responses must follow this structure:
 
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "field": "optional_field_name"
}
 
## Rules
- Never return raw exception messages to clients
- Use HTTPException with a detail dict matching the structure above
- 400 for validation errors, 404 for missing resources, 409 for conflicts
- Log the full traceback server-side before returning the sanitized response

Wijs waar mogelijk naar bestaande bestanden in je codebase in plaats van code in regels te kopiëren. Een zin als "Zie app/routers/users.py voor de canonieke endpoint-structuur" blijft accuraat terwijl de code evolueert, terwijl een gekopieerde snippet verouderd raakt zodra iemand het origineel refactort.

Regelbijlage testen en verifiëren

Cursor heeft geen ingebouwde indicator die laat zien welke regels actief zijn in een gesprek. Je verifieert het door gedrag te testen.

Open een nieuwe Agent-chat en schrijf een prompt die één van je regels zou moeten triggeren. Voor error-responses.mdc kun je proberen: "Voeg een DELETE-endpoint toe om een gebruiker op ID te verwijderen in app/routers/users.py." Als de gegenereerde foutafhandeling totaal niet lijkt op de JSON-structuur uit je regel of HTTPException met de detail-dict overslaat, klopt er iets niet in de matching.

Glob-gescopede regels hebben een matchend bestand nodig dat in je prompt wordt genoemd of open staat in de editor. error-responses.mdc testen zonder een bestand onder app/routers/ te noemen betekent dat de regel nooit activeert. 

"Apply Intelligently"-regels zijn in plaats daarvan topic-based: probeer een prompt die gerelateerd is aan de beschrijving van de regel, en vervolgens één die niet gerelateerd is, en vergelijk de outputs. De agent zou de regel bij de eerste moeten volgen en bij de tweede moeten negeren.

Je Cursor-regels effectief houden

Regels die vorige maand werkten, kunnen de AI misleiden na een refactor of een naamswijziging van een map.

Matching-fouten oplossen

De meest voorkomende reden dat een regel niet afgaat, is de bestandsextensie: regels moeten .mdc gebruiken, en gewone .md-bestanden in .cursor/rules/ worden stilletjes genegeerd.

Daarbuiten:

• Te brede globs zoals **/*.py koppelen de regel aan elk Python-bestand in het project. Vernauw naar app/routers/**/*.py of tests/**/*.py, zodat de regel alleen afgaat waar hij thuishoort.

• Je merkt dat "Apply Intelligently"-regels gesprekken missen wanneer de beschrijving te generiek is. De goede/slechte beschrijvingvoorbeelden uit de metadata-sectie hierboven gelden hier ook.

• Tegenstrijdige regels zijn lastiger te zien. Wanneer twee regels tegenstrijdige instructies geven voor dezelfde bestanden, kiest de AI er één (meestal degene die het laatst is geladen). Los dit op door de glob-scope te vernauwen zodat regels niet overlappen, of bundel gerelateerde richtlijnen in één bestand.

Een eigenaardigheid om te weten: wijzigingen in .mdc-bestanden verdwijnen soms zonder op te slaan. Als bewerkingen niet blijven staan, sluit Cursor volledig af, kies "Override" in de pop-up met niet-opgeslagen wijzigingen en open opnieuw.

Regels laten beklijven midden in een gesprek

Een regel kan aan het begin van een gesprek correct afgaan en vijf berichten later toch genegeerd worden. Recency bias van het contextvenster is de oorzaak: naarmate het gesprek groeit, geeft het model prioriteit aan recente berichten boven instructies die bovenaan zijn geïnjecteerd. Dit is de meest voorkomende klacht in de Cursor-community, en er is geen instelling die het oplost.

De workaround is versterking. Wanneer de output van je regels begint af te wijken, voeg je in je volgende prompt een regel toe als "volg de projectregels voor foutresponsen". Dat brengt de instructie weer in de recente context van het model. 

Voor regels die bij elk antwoord belangrijk zijn (opmaak, naamgeving), houden kortere en directere formuleringen beter stand in lange gesprekken dan uitgebreide alinea’s.

Regels met codevoorbeelden weerstaan drift ook beter dan alleen-tekst instructies. In plaats van te schrijven "gebruik early returns voor foutafhandeling", voeg je een kort voor/na-blok toe dat het gewenste patroon laat zien. Het model verankert zich betrouwbaarder aan echte code dan aan prozabeschrijvingen, vooral naarmate de context groeit.

Regels onderhouden en snoeien

Herzie regels na elke grote refactor, dependency-upgrade of herstructurering van mappen. Een regel die verwijst naar verouderde API’s of verwijderde bestanden geeft de AI verkeerde instructies. Stille globs zijn nog stiller in hun falen: hernoem app/api/ naar app/routers/ en een regel die op het oude pad scoped is, stopt gewoon met afgaan zonder waarschuwing.

Snoeien werkt ook de andere kant op. Naarmate modellen beter worden, pakken ze gangbare conventies op zonder dat je ze hoeft te noemen. Als de AI een regel al spontaan volgt, verwijder de regel en win de tokens terug. Een gezonde set regels krimpt in de tijd, groeit niet alleen.

Regels opschalen voor teamomgevingen

Behandel regels zoals applicatiecode. Wijzigingen gaan via pull requests en het team stemt in met een patroon voordat het in .cursor/rules/ landt.

Voor organisaties met Business- of Enterprise-plannen kunnen beheerders met Team Rules regels afdwingen voor alle leden via het Cursor-dashboard. "Enable immediately" activeert een regel standaard terwijl gebruikers hem kunnen uitschakelen. "Enforce this rule" verwijdert de opt-out, wat handig is voor niet-onderhandelbare conventies zoals securitypraktijken en compliance-eisen.

Conclusie

Begin met één of twee regels voor de patronen die je het vaakst corrigeert. Als je elke sessie hetzelfde soort AI-output blijft aanpassen (verkeerde foutindeling, onnodige abstracties), dan wacht daar een regel om geschreven te worden. Voeg er meer toe zodra je terugkerende fouten ziet, en snoei regels die geen waarde meer leveren.

De .mdc-bestanden uit deze tutorial passen bij een FastAPI-project. Die van jou zien er anders uit voor een Next.js-frontend of een Rust-CLI-tool, en dat is precies de bedoeling: ze leggen de conventies van jouw team vast, niet generieke best practices. 

Wil je dieper in Cursor duiken, bekijk dan onze Cursor 2.0-gids. Voor een vergelijking met andere AI-codeassistenten raad ik onze vergelijkende stukken aan:

• Cursor vs GitHub Copilot
• Claude Code vs Cursor
• Cline vs Cursor
• Cursor vs. Windsurf