Instructies voor je AI-agent horen in de repo: versioned, gereviewd en gesnoeid als code. Elk platform heeft er een eigen vorm voor (AGENTS.md, CLAUDE.md, copilot-instructions.md of .cursorrules), maar de gouden regel is overal gelijk: kort, universeel en actueel.

Voor wie? Developers en tech leads die met een AI-agent werken, welk platform dan ook, en willen weten hoe ze de instructies eromheen structureren.

Elke AI-coding-agent opereert in een vacuüm, totdat jij hem context geeft. Geef je geen instructies mee, dan gokt hij naar je code-afspraken en architectuuropbouw. Je merkt het meestal pas als de pull request binnenkomt.

Twee developers in de gloed van een scherm bekijken een instructiebestand in de repository, waarop een robotje het document leest
Instructies in de repo: elke agent leest dezelfde afspraken.

De meeste guides vertellen je wát er in dat instructiebestand moet. Dit artikel gaat over de opbouw: hoe je het klein houdt, laat groeien en weer snoeit. De voorbeelden komen uit mijn eigen .NET-codebase, maar het principe werkt voor elke stack en elk platform. Werk je met Claude Code, lees dan ook de toolspecifieke uitwerking in hoe bouw je context op met Claude Code?: dat artikel gaat over de laadmechanica en mijn eigen bestanden, dit artikel over het principe erachter.

Wat hoort er in een context-file?

Context is alles wat een agent helpt om betere output te leveren. Dat valt uiteen in een paar lagen, elk specifieker dan de vorige:

Laag Doel en gebruik Houdbaarheid
Instructiebestand De “grondwet” van je project: tech-stack keuzes, naamgevingsconventies, veelgebruikte commands. Permanent. Groeit in het begin snel, daarna stabiliseert het.
Modulaire regels Regels per domein, bijvoorbeeld databasetoegang of frontend-conventies. Alleen relevant zolang je in dat domein werkt. Permanent. Per domein, geraadpleegd wanneer nodig.
Herbruikbare workflows Een terugkerende taak als sjabloon vastleggen in plaats van 'm elke keer opnieuw uit te leggen. Permanent. Roep je aan wanneer je de taak nodig hebt.
Specs / plannen De blauwdruk voor één feature. Zie spec-driven development. Per feature. Kan daarna weg of naar het archief.
Je prompt De vraag die je nu stelt. Vluchtig. Alleen relevant voor de huidige sessie.

Die eerste, bredere laag heet per platform anders. AGENTS.md is de meest generieke vorm: de cross-tool-standaard waar alle vier de tools mee kunnen werken. Daarnaast heb je CLAUDE.md voor Claude Code, copilot-instructions.md voor GitHub Copilot en .cursorrules voor Cursor. Ik gebruik dit dagelijks met Claude Code, GitHub Copilot en Codex. Het principe achter alle vier is hetzelfde.

Agents onthouden ook dingen binnen een sessie, maar dat is vluchtig. Bij lange sessies wordt het gesprek samengevat en gaan details verloren. Tussen sessies is alles weg, tenzij het in een bestand staat. Daarom wordt je instructiebestand vrijwel overal automatisch geladen bij de start van een sessie, terwijl modulaire regels pas meekomen zodra je taak erom vraagt.

Dat maakt het instructiebestand je belangrijkste bestand: alles wat erin staat kost elke sessie aandacht, relevant of niet. In mijn artikel over AI-adoptie noem ik dit De Fundering: de kaders waarbinnen de agent werkt.

Instructies voor je agent horen in de repo: versioned, gereviewd en gesnoeid als code.

Wat is de gouden regel voor context-files?

Kort

<100 regels werkt beter dan 500. Hoe langer het bestand, hoe meer een agent er domweg omheen leest.

Universeel

Elke regel gaat in elke sessie mee. Zet er alleen in wat altijd relevant is. Specifieke instructies horen in een apart regelbestand of in een spec.

Actueel

Een verouderd instructiebestand is erger dan geen instructiebestand. Verouderde regels leiden tot verkeerde output. Je merkt het direct.

Waarom dit ertoe doet: een AI-agent heeft een beperkte aandachtsspanne. Voer je 'm 200 regels over CSS-naamgeving terwijl hij een SQL-bug moet oplossen, dan is dat ruis die de output verlaagt. Regels die niet relevant zijn voor de huidige taak, kosten aandacht die je liever besteedt aan het probleem zelf. En overbodige context kost ook tokens, en dus geld, per request.

Vuistregel: vraag bij elke regel “is dit altijd relevant?” Zo nee, verplaats het naar een apart regelbestand of schrap het.

Hoe bouw je zo'n bestand op?

Sommige tools genereren een eerste versie voor je (Claude Code heeft /init, andere platforms hebben vergelijkbare commando's). Dat is een startpunt, geen eindresultaat. Zet er minimaal in: je tech stack, je build/test-commands en je belangrijkste architectuurkeuzes. Review het en schrap wat niet klopt:

## Project
.NET 10 solution, multi-tenant SaaS platform

## Commands
dotnet build Invullen.sln
dotnet test

## Architecture
4 microservices, 1 frontend (MVC), 1 marketing website
Communication via REST APIs between services
Authentication: OpenID Connect with SSO towards Entra ID
Authorization: JWT bearer tokens, role-based access

Eerste weken: fouten worden regels

Zie je bij het controleren van PR's meerdere keren dezelfde fout terugkomen, dan voeg je een regel toe:

  • Agent gebruikt raw SQL → voeg toe: “gebruik altijd de repository-laag”
  • Agent vergeet [Authorize] → voeg toe: “gebruik [Authorize] op alle protected endpoints”
  • Agent genereert Console.WriteLine → voeg toe: “log via ILogger, nooit Console.WriteLine”

Dat is de feedbackloop: elke correctie die vaker terugkomt, wordt een regel in je instructiebestand.

Weken erna: splitsen en opschonen

Je instructiebestand groeit en wordt te groot. Tijd om te splitsen:

Blijft in het instructiebestand

Project structuur, build/test commands, top 10 conventies. Universeel, altijd relevant.

Verhuist naar aparte regelbestanden

security.md, ef-data-types.md, frontend-conventions.md, testing.md, exception-logging.md. Alleen relevant zolang je in dat domein werkt.

Sommige tools laden zo'n regelbestand automatisch zodra je in bijpassende bestanden werkt (Claude Code doet dit met rules), bij andere structureer je dat zelf. Het principe blijft gelijk: minder ruis, scherpere output.

Maandelijks: opschonen

  • Verwijder regels over dingen die elk model sowieso goed doet (bijv. “gebruik geen goto”)
  • Houd regels over project-specifieke keuzes die het model niet kan weten (bijv. “Newtonsoft.Json, niet System.Text.Json”)
  • Update regels die niet meer kloppen (framework geüpdatet, patronen veranderd)
  • Controleer of je aparte regelbestanden nog actueel zijn
  • Check bestandsnamen en verwijzingen: na refactoring kloppen paden vaak niet meer

Een context-file is nooit af: het bestand leeft mee met je codebase.

Welke fouten zie je het vaakst?

  • Te lang instructiebestand: honderden regels, de agent negeert een deel ervan. Schrap of splits.
  • Code-snippets in je instructiebestand: verouderen snel. Verwijs naar bestandspaden in plaats van code te kopiëren.
  • Nooit opschonen: verouderde of tegenstrijdige regels leiden tot onvoorspelbare output.
  • Alles in één bestand: specifieke regels horen in een apart regelbestand of een spec.
  • Geen feedbackloop: als je niet bijwerkt na terugkerende correcties, blijf je dezelfde bijsturing doen.

Wat moet je onthouden?

  • Je instructiebestand < 100 regels. Alles wat niet altijd relevant is, hoort ergens anders.
  • Regels zijn advies, geen garantie. Review blijft nodig.
  • Context bouw je niet in een dag. Het is een feedbackloop: elke correctie die vaker terugkomt, wordt een regel.

Hoeveel regels heeft jouw instructiebestand? En wanneer heb je het voor het laatst opgeschoond?

Hoe dit er voor één platform in de praktijk uitziet, met de 80/100-regel tussen instructies en hooks en een concreet voorbeeld uit mijn codebase, staat in hoe bouw je context op met Claude Code?