Momenteel neem ik geen nieuwe klanten aan +31 6 301 963 14 dennis@gouwers.nl
AI

Bouwafspraken voor je codeer-agent: CLAUDE.md en AGENTS.md

Bijgewerkt op 11 min leestijd

In dit artikel

AGENTS.md is een gewoon tekstbestand in een projectmap waarin staat hoe een codeer-agent in dat project moet werken: welke techniek, welke huisstijl, welke schrijfregels, welke eisen voor toegankelijkheid en wat nooit mag. Codex, Cursor en GitHub Copilot lezen het automatisch. CLAUDE.md is de eigen variant van Claude Code, dat AGENTS.md standaard alleen leest als er geen CLAUDE.md is. Het formaat is eenvoudig, de inhoud niet: de regels die ertoe doen, komen uit de keuzes en risico's van dat ene project. Bij elk project dat ik bouw, richt ik zo'n bestand in.

Wat is AGENTS.md, en wat is CLAUDE.md?

Een codeer-agent begint elke sessie blanco. Hij weet niet welke techniek een project gebruikt, welke kleuren bij de huisstijl horen of dat er nooit iets live gaat zonder test. Je kunt dat elke keer opnieuw uitleggen, of het één keer vastleggen in een bestand dat de agent bij het begin zelf leest. Dat bestand heet AGENTS.md of CLAUDE.md.

AGENTS.md is een open formaat: een gewoon Markdown-bestand, een tekstbestand met eenvoudige opmaak, in de hoofdmap van een project. De makers noemen het een README voor agents. Waar een README uitleg geeft voor mensen, geeft AGENTS.md uitleg voor AI. OpenAI bracht het formaat in augustus 2025 uit. Sinds december 2025 valt het onder de Agentic AI Foundation van de Linux Foundation, samen met onder meer MCP, de standaardstekker tussen AI en software. Volgens agents.md gebruiken meer dan 60.000 opensourceprojecten het (stand november 2026).

CLAUDE.md is hetzelfde idee, maar dan het eigen bestand van Claude Code, de codeer-agent van Anthropic. Wat Claude Code is en waar zelf bouwen ermee ophoudt, lees je in website bouwen met Claude Code.

Het bestand zelf is dus niets bijzonders. Wat het waardevol maakt, is wat erin staat. Bij elk project dat ik bouw, richt ik zo'n bestand met bouwafspraken in: techniek, huisstijl, schrijfregels, toegankelijkheid en wat nooit mag. Zo werkt de agent bij elke wijziging volgens dezelfde regels, ook als die wijziging maanden na de bouw komt.

Welke codeer-agent leest welk bestand?

Elke tool heeft zijn eigen voorkeuren, maar AGENTS.md wordt steeds breder gelezen. Zo zit het, stand november 2026:

Tool Leest automatisch Goed om te weten
Claude Code CLAUDE.md, en in recente versies AGENTS.md als er geen CLAUDE.md is Met de regel @AGENTS.md in de CLAUDE.md leest hij allebei
Codex (OpenAI) AGENTS.md Kent ook een persoonlijk bestand voor al je projecten; leest standaard tot 32 KiB aan instructies
Cursor AGENTS.md en eigen regels in de map .cursor/rules Leest ook AGENTS.md-bestanden in submappen
GitHub Copilot .github/copilot-instructions.md en AGENTS.md Kan ook een CLAUDE.md of GEMINI.md in de hoofdmap gebruiken

Werkt een project met één tool, dan volstaat het bestand van die tool. Wordt er met meerdere tools gewerkt, of moet een opvolger met een andere tool verder kunnen, dan is AGENTS.md de gedeelde basis. Dat laatste is meer waard dan het lijkt. Een goed bestand met bouwafspraken is ook documentatie voor de volgende mens die aan de site werkt, zoals de collega-freelancer die bij nood mijn beheer overneemt. Welke andere stukken bij een overdracht horen, staat in website bij één beheerder.

Wat hoort er in een AGENTS.md met bouwafspraken?

Een goed bestand beantwoordt de vragen die een nieuwe collega op zijn eerste dag zou stellen. In mijn projecten komen altijd vijf onderwerpen terug. De koppen zijn overal hetzelfde; de inhoud is per project anders, en daar zit het werk.

1. Techniek

Welke techniek gebruikt het project, hoe start je de site lokaal, hoe bouw je hem en hoe test je? Waar staan welke bestanden? Een agent die weet dat een site met Eleventy is gebouwd en waar de inhoud staat, zoekt niet op de verkeerde plek en verzint geen eigen opbouw. De commando's staan er letterlijk in, zodat de agent zijn eigen werk kan controleren. Dat werkt alleen als die controles bestaan: een bestand kan niet verwijzen naar een test die niemand heeft gebouwd.

2. Huisstijl

Kleuren, lettertypes, afstanden en vaste onderdelen zoals knoppen en kaarten. Een regel als 'gebruik alleen de vaste kleuren' heeft pas betekenis als die kleuren ergens zijn vastgelegd, bijvoorbeeld in een stijlbestand met vaste waarden. Zonder die basis verzint een agent graag een nieuwe tint blauw of een knop die net iets anders is. Hoe je zulke vaste waarden en onderdelen opzet, lees je in design system.

3. Schrijfregels

Je of u? Welke woorden nooit? Hoe schrijf je bedragen en data? Een agent past regelmatig ook teksten aan, en dan moeten ze klinken als het merk. Dat kan alleen als die toon eerst is bepaald: een agent kan geen regels volgen die niemand heeft opgeschreven. Hoe je je toon vastlegt, staat in tone of voice vastleggen.

4. Toegankelijkheid

Elke afbeelding een beschrijvende alt-tekst, elk formulierveld een label, één hoofdkop per pagina, voldoende contrast en alles bedienbaar met het toetsenbord. Een agent vergeet dat soort details makkelijk als ze nergens staan. Welke regels erin horen, hangt af van wat de norm vraagt en waar een site kwetsbaar is, zoals formulieren of video. De eisen zelf staan in WCAG 2.2, vertaald naar gewone taal.

5. Wat nooit mag

Dit is het belangrijkste onderwerp, en het meest projectgebonden. Staat een verbod op papier, dan voegt een agent niet even iets toe omdat dat handig leek. Sommige verboden gelden overal: geen wachtwoorden of sleutels in de code, geen nieuwe pakketten zonder reden, geen teksten verzinnen die niet zijn aangeleverd.

Andere verboden volgen uit dat ene project, en die kun je pas opschrijven als je weet waarom ze nodig zijn. Neem een site met een inschrijfformulier waarop mensen medische of andere gevoelige gegevens invullen. Dan hoort in de bouwafspraken dat op die pagina's geen tracker of ander script van een externe partij komt. Die gevoeligheid, en niet de techniek, bepaalt hier wat er wel en niet op een pagina mag.

Waarom een standaardsjabloon niet werkt

Op internet staan genoeg voorbeeldbestanden, en een agent maakt op verzoek in een minuut een eerste versie. Dat lijkt het werk klaar te maken. Toch ontbreekt dan precies het deel dat ertoe doet.

  • Een sjabloon beschrijft wat er is, niet wat er besloten is. Een agent die een project scant, ziet welke techniek er draait en welke commando's bestaan. Hij ziet niet dat de klant nooit met u wil worden aangesproken, dat een pagina buiten Google moet blijven of dat er op een formulier geen tracker mag komen.
  • Een overgenomen bestand brengt andermans keuzes mee. Regels die voor een ander project logisch waren, botsen met de opbouw van deze site. Een agent die tegenstrijdige regels krijgt, kiest er willekeurig één.
  • Algemene regels zijn niet te controleren. 'Houd de stijl consistent' klinkt goed, maar niemand kan nagaan of de agent zich eraan hield. 'Knoppen alleen met de klasse knop' kan dat wel.
  • De risico's verschillen per project. Een praktijksite met een inschrijfformulier vraagt andere verboden dan een webshop met een configurator of een site met alleen informatie.

Goede bouwafspraken schrijven is daarom geen invuloefening. Het vraagt kennis van de techniek, van privacy en toegankelijkheid, en van de fouten die een agent in de praktijk maakt. Dat is werk dat ik per project doe, bij de bouw en daarna in het beheer van de site.

Een voorbeeld: zo zien bouwafspraken eruit

Een voorbeeld, voor een verzonnen schildersbedrijf. De inhoud is fictief en ingekort, de vijf onderwerpen zijn dezelfde als in de bouwafspraken van mijn eigen projecten. Het laat zien hoe concreet de regels zijn, niet wat er voor een andere site in zou moeten.

## Techniek
- Statische site met Eleventy, gehost op Netlify.
- Pagina's staan in src/, gedeelde onderdelen in src/_includes/.
- Adres, telefoon en openingstijden staan alleen in src/_data/bedrijf.json.
  Zet ze nooit los in een pagina.
- Lokaal starten: npm start. Bouwen: npm run build.
- Controleer na elke wijziging of npm run build zonder fouten draait.
- Leg elke wijziging vast in Git met een omschrijving in gewone taal.

## Huisstijl
- Kleuren en afstanden alleen via de variabelen in src/css/basis.css.
- Knoppen: gebruik de klasse knop of knop-secundair. Geen nieuwe varianten.

## Schrijfregels
- Spreek de lezer aan met je. Korte zinnen.
- Bedragen als € 1.250, data als 6 november 2026.
- Nooit gebruiken: uitroeptekens, 'innovatief', 'oplossingen op maat'.

## Toegankelijkheid
- Elke afbeelding een alt-tekst die zegt wat erop staat.
- Elk formulierveld een zichtbaar label.
- Eén H1 per pagina. Alles bruikbaar met het toetsenbord.

## Wat nooit mag
- Geen wachtwoorden, sleutels of tokens in de code.
- Geen externe scripts, trackers of lettertypes van buiten zonder overleg.
- Geen nieuwe pakketten zonder overleg.
- Geen teksten verzinnen: gebruik alleen aangeleverde tekst.

Elke regel is concreet genoeg om te controleren, en achter elke regel zit een reden. De commando's staan erin, zodat de agent zelf kan testen of zijn werk de site niet breekt. Het adres staat op één plek, met de afspraak dat het nergens anders mag staan; zo typt een agent geen telefoonnummer los in een pagina dat bij de volgende wijziging wordt vergeten. En lettertypes van buiten staan op de verbodslijst omdat ze bij elk bezoek gegevens van bezoekers naar een ander bedrijf kunnen sturen. Voor een ander bedrijf zou een deel van deze regels anders luiden.

Hoe bouwafspraken zorgen voor consistentie

Zonder afspraken kiest een agent bij elke opdracht opnieuw. De ene keer een knop in de bestaande stijl, de andere keer een nieuwe variant. De ene keer u, de andere keer je. Elke keuze apart is te verdedigen, maar na twintig wijzigingen heb je een site die rammelt.

Met een bestand met bouwafspraken begint elke sessie met dezelfde regels. Dat geeft drie dingen:

  • dezelfde uitkomst bij dezelfde vraag, ook maanden later en met een ander model;
  • minder uitleg per opdracht, omdat de vaste dingen al vastliggen;
  • een maatstaf bij de controle: bij het nakijken vergelijk ik de wijziging met de afspraken. Hoe ik een wijziging doorvoer, lees je in website aanpassen met AI.

Eén kanttekening is belangrijk. Volgens de documentatie van Claude Code behandelt de agent CLAUDE.md als context, niet als afgedwongen instelling. Een agent kan een regel dus toch overslaan, zeker als het bestand lang is of regels elkaar tegenspreken. Wat echt nooit mag gebeuren, hoort daarom ook in de instellingen van de tool, bijvoorbeeld met een blokkade op bepaalde commando's. Daarnaast blijft mijn eigen controle van elke wijziging nodig; daarover gaat AI-code controleren.

Zo richt ik de bouwafspraken per project in

Een goed bestand ontstaat niet in één keer. Het begint bij de keuzes die bij de bouw worden gemaakt en groeit mee met het project. Dit zijn de eisen waar ik het aan toets:

  • Concreet en controleerbaar. 'Draai npm run build voordat je iets vastlegt' werkt beter dan 'test je wijzigingen'.
  • Kort. Anthropic adviseert minder dan 200 regels per CLAUDE.md. Hoe langer het bestand, hoe slechter de agent het volgt. Er staat dus alleen in wat de agent niet zelf uit het project kan halen.
  • Geen tegenstrijdigheden. Twee regels die botsen, maken de agent onvoorspelbaar.
  • Met reden erbij. Een regel met uitleg helpt de agent ook in gevallen die niemand had voorzien.
  • Bijwerken als het misgaat. Maakt de agent twee keer dezelfde fout, dan hoort er een regel bij. Ook Anthropic noemt dat als moment om het bestand aan te vullen.
  • Geen geheimen. Het bestand staat in de projectmap en in versiebeheer, dus er staan nooit wachtwoorden of sleutels in.
  • Een eerste versie van de AI is een begin, geen eindproduct. In Claude Code maakt het commando /init een eerste CLAUDE.md op basis van het project. Daarna begint het werk: aanvullen met wat de agent niet kan ontdekken, zoals de schrijfregels en wat nooit mag.

CLAUDE.md en AGENTS.md naast elkaar: één bron

Wordt er met Claude Code en ook met andere tools gewerkt, dan wil je de afspraken niet twee keer bijhouden. Dat hoeft niet. De afspraken staan dan in AGENTS.md, en de CLAUDE.md begint met de regel @AGENTS.md. Claude Code leest dan eerst AGENTS.md en daarna wat er verder in CLAUDE.md staat, zoals afspraken die alleen voor Claude gelden. Zo staat alles op één plek. Hoe dat precies werkt, staat in de documentatie van Claude Code.

Nog drie dingen om te weten:

  • Bestanden in submappen zijn mogelijk. Bij AGENTS.md gaat het bestand voor dat het dichtst bij het bewerkte bestand staat. Handig als een deel van het project eigen regels heeft.
  • Persoonlijke voorkeuren horen niet in het projectbestand. Claude Code kent daarvoor een bestand in de eigen gebruikersmap, dat voor alle projecten geldt. Codex heeft iets vergelijkbaars.
  • Een opdracht in de chat gaat voor. Wat in een sessie expliciet wordt gevraagd, weegt zwaarder dan het bestand. Handig voor een uitzondering, maar een uitzondering die vaker voorkomt, hoort in het bestand zelf.

Conclusie: het bestand is simpel, goede bouwafspraken zijn vakwerk

AGENTS.md en CLAUDE.md zijn gewone tekstbestanden die een codeer-agent bij het begin van elke sessie leest. Het bestand is in een minuut gemaakt. De inhoud niet: welke techniek, welke huisstijl, welke schrijfregels, wat toegankelijkheid vraagt en vooral wat nooit mag, verschilt per project en vraagt kennis van wat er mis kan gaan. En omdat een agent de afspraken leest als context en niet als wet, blijft elke wijziging een controle waard.

Die afspraken schrijf ik per project, en wat de agent daarna maakt, kijk ik zelf na. Jij hoeft er niets van te weten; je merkt alleen dat je site na twintig wijzigingen nog steeds klopt. Welke vragen je een bouwer kunt stellen om te zien of hij AI-code goed nakijkt, staat in AI-code controleren. Benieuwd hoe ik met AI werk voor bedrijven? Download het pitchdeck.

Veelgestelde vragen

Wat is het verschil tussen AGENTS.md en CLAUDE.md?

Het idee is hetzelfde: een tekstbestand met vaste instructies dat een codeer-agent aan het begin van een sessie leest. AGENTS.md is een open formaat dat veel tools lezen, waaronder Codex, Cursor en GitHub Copilot. CLAUDE.md is het eigen bestand van Claude Code. Recente versies van Claude Code lezen AGENTS.md ook, maar standaard alleen als er geen CLAUDE.md is. Staat in de CLAUDE.md de regel @AGENTS.md, dan leest Claude Code allebei. Zo blijft er één bestand met afspraken voor alle tools.

Waar zet je het AGENTS.md-bestand?

In de hoofdmap van het project, naast bijvoorbeeld de README. Daar zoeken codeer-agents er standaard naar. Heeft een deel van het project eigen regels, dan kan in die submap een extra AGENTS.md staan. Het bestand dat het dichtst bij het bewerkte bestand staat, gaat dan voor. Het bestand hoort in versiebeheer, zodat iedereen die aan het project werkt dezelfde afspraken heeft, mens of agent.

Hoe lang mag een CLAUDE.md of AGENTS.md zijn?

Zo kort als het kan. Anthropic adviseert minder dan 200 regels per CLAUDE.md, omdat een langer bestand meer ruimte in het werkgeheugen van de agent inneemt en slechter wordt opgevolgd. Codex leest standaard tot 32 KiB aan instructies en houdt daarna op. Er hoort dus alleen in wat de agent niet zelf uit het project kan halen: afspraken, keuzes en verboden. Regels die maar voor een deel van het project gelden, staan beter in een apart bestand in die submap.

Kan ik een AGENTS.md-sjabloon van internet gebruiken?

Als voorbeeld van de vorm wel, als inhoud zelden. Een sjabloon geeft de koppen, maar de regels die ertoe doen, horen bij één project: de techniek, de huisstijl, de toon en vooral de risico's, zoals een formulier met persoonsgegevens of pagina's waar geen trackers mogen draaien. Een overgenomen bestand brengt de keuzes van een ander mee, en regels die niet bij de site passen of elkaar tegenspreken, maken de agent juist onvoorspelbaarder. Daarom schrijf ik de bouwafspraken per project.

Kan AI zelf een AGENTS.md of CLAUDE.md schrijven?

Een eerste opzet wel. In Claude Code maakt het commando /init een CLAUDE.md op basis van het project, met onder meer de commando's om te bouwen en te testen. Ook andere agents maken een opzet als je dat vraagt. Maar de AI ziet alleen wat er in de code staat. Wat er voor een bedrijf toe doet, zoals de schrijfregels, de privacyverplichtingen en wat nooit mag, kan hij niet afleiden. Dat deel vraagt kennis van het project en van wat er mis kan gaan, en daar zit het vakwerk.

Benieuwd hoe ik dit in de praktijk aanpak?

Het pitchdeck laat de hele werkwijze zien.

Geschreven door

Marketing freelancer uit 's-Hertogenbosch. Volg op LinkedIn (opent in een nieuw tabblad)