CLAUDE.md en AGENTS.md: wat ik na 42 projecten invul

Update (9 november 2026): Claude Fable 5.2 en Mythos 5.2 zijn uit - prijzen, toegang en benchmarks in mijn gids over Claude Fable 5.2.

👁 114 keer gelezen

Op mijn schijf staan 42 bestanden met instructies voor AI-agents: 16 CLAUDE.md-bestanden en 26 AGENTS.md-bestanden, elk in de map van een ander project. Het kortste bestand telt één regel, het langste 402. Dat langste bestand is twee keer zo lang als Anthropic aanbeveelt. Ik begin ermee, want het laat goed zien wat er in zo’n bestand terechtkomt.

Wat is CLAUDE.md?

Het is een gewoon Markdown-bestand dat Claude Code aan het begin van elke sessie leest. Elk gesprek met een agent begint met een leeg geheugen. Alles wat niet uit de code valt af te leiden, moet je dus opnieuw vertellen. CLAUDE.md doet dat voor je: commando’s voor tests, projectregels, dingen die de agent niet mag doen en valkuilen waar je zelf al tegenaan bent gelopen.

De documentatie van Claude Code maakt duidelijk dat het bestand context biedt en geen harde configuratie is. De agent houdt zich er meestal aan, maar dat hoeft niet. Wil je iets altijd blokkeren, zoals bestanden verwijderen of een implementatie op een server uitvoeren, gebruik dan hooks en machtigingen in de instellingen. Een zin in CLAUDE.md is daarvoor niet genoeg.

Waar staat het bestand en wat wordt ingelezen?

Er kunnen meerdere bestanden tegelijk zijn. Claude Code kiest er niet één uit, maar voegt alle gevonden bestanden samen, van de meest algemene tot het bestand dat het dichtst bij de map staat waarin je werkt.

Bestanden in mappen boven de locatie waar je de agent start, worden meteen ingelezen. Bestanden in submappen komen pas aan bod wanneer de agent daar bestanden gaat lezen of aanpassen. Zo nemen instructies voor de frontend in een grote repository geen ruimte in wanneer de agent aan de database werkt.

Je kunt een eerste versie maken met het commando /init. Claude bekijkt de code en noteert commando’s en conventies die het zelf vindt. Dat is een goed begin, maar ik vul de rest altijd met de hand aan. De waardevolste regels zijn namelijk juist de regels die je niet uit de code kunt afleiden.

Mijn langste bestand: 402 regels

De documentatie raadt aan om één CLAUDE.md-bestand onder de 200 regels te houden. Een langer bestand neemt context in beslag en de agent houdt zich er minder goed aan. Mijn bestand voor het project Jantaris telt 402 regels en 46.095 bytes. Van mijn 16 CLAUDE.md-bestanden overschrijdt alleen dit bestand de limiet; de mediaan is 35 regels.

Het is niet in één keer ontstaan. Na elke fout kwamen er nieuwe valkuilen bij: hoe de server afbeeldingen cachet en waarom een vervangen bestand met dezelfde naam gebruikers pas na een week bereikt, hoeveel registraties per uur de beveiliging toestaat en hoe tests die limiet moeten resetten, waar de server staat en hoe e-mail wordt verstuurd. Elke regel herinnert aan een concreet probleem. Samen werd het te veel.

Mijn mening: CLAUDE.md is geen projectdocumentatie, maar een kaart van mijnen. De agent kan uit de code en README afleiden hoe de applicatie werkt. In CLAUDE.md hoort wat niet uit de code blijkt, maar eerder wel eens mis is gegaan. Als het bestand langer wordt dan 200 regels, splits ik het op in thematische bestanden in .claude/rules/. Importeren met @bestand.md helpt alleen om de boel te ordenen: het geïmporteerde bestand wordt nog steeds helemaal ingelezen.

Het voorbeeldbestand uit mijn cursus: 34 regels

Een goed voorbeeld is de CLAUDE.md van het project ‘Reparatiedatabase’, een applicatie voor een autogarage die we vanaf nul bouwen in mijn cursus Een SaaS bouwen in een weekend met Claude Code. Hier staat het hele bestand, zonder inkortingen:

# Reparatiedatabase - notities voor de agent

Product, schermen en regels: @SPEC.md
Bouw alleen het onderdeel MOET ERIN uit SCOPE.md. Zet ideeën buiten
de scope bij LATER, met een voorwaarde om ze weer op te pakken, en vraag het aan mij.

## Stack
- Node 22.13+, geen npm-afhankelijkheden: node:http, node:sqlite, node:test, fetch.
- SQLite in data/app.db, migraties in migrations/NNN_naam.sql.
- HTML wordt op de server gerenderd; in de browser gebruiken we gewone JS.

## Commando's
- npm run dev                 server op poort 8080, opnieuw starten na een bestandswijziging
- npm test                    node --test "test/*.test.js" (glob tussen aanhalingstekens)
- npm run reset               database opnieuw opzetten + testdata + testaccounts
- python tools/screenshots.py URL  screenshots op 1440 px en 390 px in data/shots/

## Regels
- Bedragen in centen als INTEGER. Gebruik nooit getallen met decimalen.
- De server controleert de plangrenzen (R1-R3). De browser toont ze alleen.
- Elke R-regel uit SPEC.md heeft een test met het regelnummer in de naam.
- Sla tekstbestanden op met LF-regeleinden.
- Gebruik in teksten alleen het koppelteken "-". De test controleert alle sjablonen.

## Verboden
- Lees .env niet. Voer geen implementatie uit. Gebruik geen git push, git reset of git clean.
- Voer geen tests uit op data/app.db (tests gebruiken een database in het geheugen).
- Importeer geen fabrieksgegevens (Autodata, HaynesPro, portals van fabrikanten):
  fabrikantenlicenties en databankbescherming in de EU.

## Valkuilen
- Git Bash past paden aan: gebruik MSYS_NO_PATHCONV=1 vóór een commando met /...
- Sla bestanden met reguliere expressies op met de bestandstool,
  niet met een heredoc in bash (backslashes verdwijnen).

Elke sectie heeft een reden:

• Verwijzing naar de specificatie. De productbeschrijving staat in SPEC.md; CLAUDE.md importeert die alleen. De regel over het onderdeel MOET ERIN houdt de agent binnen de afgesproken scope. Zonder die regel krijg je na een uur functies waar niemand om heeft gevraagd.
• Commando’s met de exacte syntaxis. De glob tussen aanhalingstekens bij de tests is een syntactisch detail dat je makkelijk over het hoofd ziet. Toch bepaalt het of alle testbestanden worden uitgevoerd.
• Regels die controleerbaar zijn. Bedragen in centen, limieten aan de serverkant en een test voor elke regel. Niets vaags als ‘schrijf nette code’, want dat kun je niet controleren.
• Verboden. De belangrijkste verboden neem ik ook op in de instellingen voor machtigingen, want een bestand is slechts een verzoek.
• Omgevingsvalkuilen. Windows en Git Bash maken paden die met een schuine streep beginnen soms kapot. De agent weet dat niet totdat een commando mislukt.

De regel die me een redactieronde kostte

Een voorbeeld maakt het duidelijk. Op 30 oktober werd tijdens het redigeren van teksten voor het tijdschrift DYGOT een script uitgevoerd dat de actuele stand van de server ophaalt. Dat gebeurde tussen het aanpassen en uploaden door. Het overschreef de lokale wijzigingen, waardoor de eerste redactieronde verloren ging. Sindsdien staat er in het instructiebestand voor dat project: ‘Voer dit ALLEEN uit vóór je aan het werk gaat - tussen het bewerken en uploaden overschrijft het je wijzigingen.’ Geen generator zou die regel hebben bedacht, want uit de code van het script valt niet af te leiden wanneer je het mag uitvoeren.

AGENTS.md: hetzelfde idee voor andere agents

AGENTS.md is hetzelfde soort instructiebestand, maar met een naam die verschillende tools herkennen: Codex van OpenAI, Cursor, Gemini CLI, de agent van GitHub Copilot en nog een tiental andere. De Agentic AI Foundation van de Linux Foundation beheert het formaat. Ik heb er 26; de mediaan is 8 regels, omdat de meeste een enkele grafische taak voor Codex beschrijven.

Claude Code kan ook AGENTS.md lezen, sinds versie 2.1.277. Standaard gebeurt dat alleen als er geen CLAUDE.md in het project staat. Als beide bestanden bestaan, leest Claude zijn eigen bestand en slaat het AGENTS.md over. Wil je dat beide tools dezelfde regels krijgen, zet ze dan in AGENTS.md en voeg in CLAUDE.md één importregel toe: @AGENTS.md. Hoe je de hele set verplaatst, inclusief skills en MCP-servers, beschreef ik in Claude Code overzetten naar Codex.

Voor projecten waaraan Claude en Codex om beurten werken, heb ik nog een regel aan het einde van het bestand: noteer na afloop het werk in een gedeeld agentenlogboek, met de datum, de naam van de agent en een lijst met wijzigingen. De volgende agent leest het logboek voordat die begint en ziet wat de vorige heeft veranderd. Dat is eenvoudiger dan het geheugen van beide tools synchroniseren.

Wat ik er niet in zet

• Sleutels en wachtwoorden. Het projectbestand belandt vaak in de repository. In mijn bestanden staat eerder een verbod om .env te lezen dan de inhoud ervan.
• Mapstructuren. De agent ziet die zelf binnen een paar seconden. Een beschrijving in het bestand is al verouderd na de eerste wijziging.
• Vage formuleringen. ‘Let op kwaliteit’ verandert niets. ‘Elke regel heeft een test met het regelnummer in de naam’ wel.
• Tegenstrijdige regels. De documentatie waarschuwt dat Claude bij twee tegenstrijdige instructies willekeurig kan kiezen. Ik lees mijn bestanden af en toe door en verwijder wat niet meer geldt.
• Notities voor mensen. Als die moeten blijven staan, zet ik ze in een HTML-commentaar <!-- -->. Claude Code verwijdert zulke commentaren voordat het het bestand inleest, dus ze kosten geen context.

Waar begin je?

Als je met Claude Code begint, schrijf dan niet alvast een CLAUDE.md. Voer /init uit, houd wat zinvol is en voeg telkens één regel toe wanneer de agent dezelfde fout voor de tweede keer maakt. Na een week heb je een bestand dat jouw project beschrijft, niet een project uit een handleiding. De installatie en eerste stappen staan in mijn gids Claude Code installeren; de kosten van de abonnementen bespreek ik in Wat kost Claude Code?.

In de cursus Een SaaS bouwen in een weekend met Claude Code schrijven we stap voor stap de specificatie en CLAUDE.md: 30 lessen, van de vraag of er belangstelling is voor een idee tot de database, inloggen, betalingen en de implementatie op je eigen server.

Bronnen en controledatum

Stand van zaken op 6 november 2026.

• CLAUDE.md- en AGENTS.md-bestanden uit mijn projecten (42 bestanden na het verwijderen van duplicaten en een repository van iemand anders), geteld op 6 november 2026
• Claude Code-documentatie: How Claude remembers your project (CLAUDE.md, AGENTS.md, imports en de limiet van 200 regels)
• AGENTS.md - uitleg over het formaat

// lees verderIs Claude Sonnet 5.5 de moeite waard voor jouw project?NieuwsAnthropics biolab ontdekt nieuw enzym via bijna 950 Claude-agentsAI-overzichtClaude Code lanceert vernieuwde Projects-functie voor teams van AI-agentenAI-tools

Kinetyra