Eén instructiebestand voor Claude Code, Codex en Cursor in 2026

Zie de Ailoot-documentatie voor informatie over de service.

Wat verandert er als je Claude Code, Codex en Cursor samen gebruikt?#

In het beschreven voorbeeld is Claude Code de hoofdtool, terwijl Codex en Cursor voor specifieke taken worden gebruikt. Mijn CLAUDE.md bevat ongeveer 250 regels instructies: wat je moet lezen en in welke volgorde, wat je niet mag aanraken, welke opdrachten je voor deployment moet gebruiken en de regels voor de commitopmaak. Toen ik Codex CLI voor het eerst op het project probeerde, kende het geen van de regels: het voerde git push --force uit, snuffelde in .env en hernoemde bestanden onzorgvuldig.

Ik kopieerde CLAUDE.md eerst handmatig naar AGENTS.md. Twee weken later ontdekte ik dat het project al vier versies van dezelfde instructie had: in CLAUDE.md, AGENTS.md, .cursorrules en .windsurf/rules/. Ze verschilden allemaal een beetje. Dit is geen probleem van Claude of Cursor; het is de klassieke valkuil van elk systeem met meerdere bronnen van waarheid. Ik bespreek dit probleem uitgebreider in de gids voor werken met meerdere agents.

In juni 2026 bood Anthropic in de documentatie over het geheugen van Claude Code één oplossing: een gedeeld bestand plus een import. Sinds september 2026 leest Claude Code AGENTS.md zelf als het project geen CLAUDE.md heeft; een import is nodig wanneer je regels specifiek voor Claude hebt. Hieronder leg ik uit wanneer één AGENTS.md volstaat, hoe je een import instelt en hoe je gedeelde regels van Claude-specifieke regels scheidt.

Leest Claude Code AGENTS.md zelf?#

Vóór september 2026 was het antwoord “nee”. Issue #6235, waarin ondersteuning voor AGENTS.md werd gevraagd, stond sinds augustus 2025 open en werd op 17 augustus 2026 gesloten. De geheugendocumentatie wees al die tijd op één oplossing: maak een CLAUDE.md en neem daarin AGENTS.md op als import. Vanaf versie 2.1.277 zegt de documentatie iets anders:

Welke bestanden Claude Code precies leest, hangt af van de bestanden in het project:

Voor deze controle tellen CLAUDE.md, .claude/CLAUDE.md en CLAUDE.local.md in de werkmap en elke bovenliggende map mee. Een persoonlijk ~/.claude/CLAUDE.md, een door het bedrijf beheerd bestand en regels uit .claude/rules/ tellen niet mee: die worden naast AGENTS.md geladen.

Als er geen CLAUDE.md is, leest Claude Code bij het opstarten alle bestanden AGENTS.md en .claude/AGENTS.md in de werkmap en bovenliggende mappen; een AGENTS.md in een submap wordt opgehaald wanneer Claude Code een bestand in die submap opent. @path-imports in AGENTS.md werken ook. Claude Code leest AGENTS.local.md, AGENTS.override.md of de inhoud van de map .agents/ niet.

De adder onder het gras: ook een persoonlijke CLAUDE.local.md telt mee. Maak je die aan om je niet-gecommitte regels bij te houden, dan stopt Claude Code stilzwijgend met het lezen van AGENTS.md. De instelling hieronder biedt de oplossing.

Je kunt het gedrag wijzigen in /config, onder Project instructions:

Als je CLAUDE.local.md wilt behouden zonder AGENTS.md kwijt te raken, stel je claude-md-and-agents-md in. Er worden geen bestanden dubbel gelezen: als AGENTS.md al is opgenomen via de regel @AGENTS.md of een symbolische link, laadt Claude Code het niet nogmaals, ongeacht de instelling.

Met de opdracht /memory kun je controleren of het bestand is opgepikt: vanaf versie 2.1.280 verschijnt het pad naar AGENTS.md in de lijst. In versies ouder dan 2.1.277 en in sessies waarin de ingebouwde plugin agents-md is uitgeschakeld, leest Claude Code alleen CLAUDE.md en is er geen item Project instructions in /config. Vóór versie 2.1.281 werkten sessies via Amazon Bedrock en sessies met uitgeschakelde telemetrie op dezelfde manier. In de eerste sessie na een update vanuit een oudere versie wordt AGENTS.md mogelijk ook niet opgepikt; vanaf de volgende sessie werkt het wel.

Wat betekent dit voor een setup met één bestand? Als je geen regels hebt die alleen voor Claude gelden, kun je CLAUDE.md overslaan: AGENTS.md is genoeg en Claude Code, Codex en Cursor zullen het lezen. Heb je zulke regels wel (plan mode voor risicovolle mappen, skills, hooks), dan heb je CLAUDE.md nodig en stopt Claude Code met het zelfstandig lezen van AGENTS.md. Neem AGENTS.md dan in CLAUDE.md op met de regel @AGENTS.md; deze setup werkt net als vóór september. Ook voor oudere versies van Claude Code is dit handig. Hieronder leg ik het uitvoerig uit.

Hoe importeer je @AGENTS.md in CLAUDE.md?#

Een minimaal werkend voorbeeld uit de officiële documentatie:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Dit gebeurt er. De eerste regel, @AGENTS.md, is een importinstructie. Wanneer Claude Code aan het begin van een sessie CLAUDE.md verwerkt, vindt het deze import en plaatst het de volledige inhoud van AGENTS.md op die plek. Daarna volgt de kop ## Claude Code: dat is gewone markdown, maar die dient als een sectie met “Claude-specifieke aanvullingen”. Daaronder staat een regel die alleen voor Claude Code geldt: gebruik plan mode voor wijzigingen in de billing-map. Codex CLI of Cursor opent dit bestand helemaal niet; die gebruiken het gewone AGENTS.md.

Een citaat uit de documentatie over de werking van imports:

Een paar praktische details:

• Relatieve en absolute paden. @AGENTS.md is relatief aan het bestand dat de import bevat. @/Users/me/shared/rules.md of @~/.claude/personal.md zijn absolute paden. Ik gebruik @~/.claude/personal.md voor persoonlijke voorkeuren die ik niet in de repository wil zetten.
• Vier niveaus diep. AGENTS.md kan @docs/coding-style.md importeren, en coding-style.md kan weer iets anders importeren, tot vier niveaus diep. Dat volstaat voor elke realistische structuur.
• Backticks blokkeren imports. Als de tekst `@README` zegt, is dat alleen een verwijzing naar de naam, geen import. Dit is handig wanneer je aan lezers uitlegt hoe imports werken zonder er een te activeren.
• Toestemming voor bestanden buiten het project. Als een import verwijst naar een bestand buiten de werkmap, zoals @~/.claude/personal.md, toont Claude Code de eerste keer een dialoog met een lijst van die bestanden. Als je weigert, blijven externe imports uitgeschakeld en wordt de dialoog niet opnieuw getoond. @AGENTS.md in de hoofdmap van het project activeert geen dialoog. Dit beschermt je tegen het per ongeluk laden van een niet-gerelateerd bestand in de context.

Nadat ik in het beschreven project naar deze setup was overgestapt, kromp mijn CLAUDE.md van 250 naar 60 regels: @AGENTS.md plus vijf tot zeven regels die alleen voor Claude Code gelden (plan mode voor risicovolle mappen, wat je in het beheergedeelte niet mag aanraken en hoe je commits formuleert). Alles wat gedeeld is, staat in AGENTS.md, dat Codex en Cursor lezen.

Wanneer kies je een symbolische link en wanneer een import?#

De documentatie toont de optie met een symbolische link als volgt:

ln -s AGENTS.md CLAUDE.md

Daarna volgt meteen een openhartige waarschuwing over Windows:

Vergelijkingstabel:

In het beschreven project gebruik ik imports. Dit zijn de redenen:

1. Het team is gemengd. Ik gebruik een Mac; in het voorbeeld is het team ongeveer gelijk verdeeld over Windows en Mac. Als er een symbolische link in de repository staat, wordt die voor Windows-gebruikers zonder Developer Mode uitgecheckt als een gewoon tekstbestand met één regel, AGENTS.md. Dat veroorzaakt vreemde bugs: soms werken de regels, soms niet, en het is onduidelijk waarom.
2. Ik wil Claude-specifieke regels. Onder @AGENTS.md staat in mijn CLAUDE.md een sectie “Claude Code” met regels: gebruik --effort high voor architectuurtaken, voer npm run build uit vóór git push en roep /api/v1/deploy niet handmatig aan. Codex begrijpt deze opdrachten niet.
3. Het is eenvoudiger om fouten op te sporen. Als er iets misgaat, open ik CLAUDE.md en zie ik de import en mijn aanvullingen. Bij een symbolische link staat er niet bij: “dit is hier toegevoegd”. Lees de gids voor de veilige modus voor meer informatie over het opsporen van problemen met Claude Code-instellingen.

Als je geen Claude-specifieke regels hebt, is een symbolische link vanaf versie 2.1.277 niet meer nodig: verwijder CLAUDE.md en Claude Code leest AGENTS.md zelf. Houd de symbolische link alleen als iemand in het team een oudere versie dan 2.1.277 gebruikt en niet kan bijwerken. Heb je Claude-specifieke regels, dan is een import in negen van de tien gevallen handiger.

Wat lezen Codex, Cursor, Copilot, Windsurf en Gemini CLI?#

Een overzicht van de zeven belangrijkste tools (gebaseerd op de officiële documentatie van elke tool):

Wat betekent dit? Als een repository AGENTS.md heeft (plus een CLAUDE.md met een import als Claude-specifieke regels nodig zijn), krijgen vijf van de zeven tools automatisch actuele instructies. Cursor en Windsurf, die eigen bestanden hebben, kun je laten zoals ze zijn (AGENTS.md wordt ook door hen gelezen) of een import @AGENTS.md toevoegen; hun syntaxis verschilt echter en wordt niet altijd ondersteund.

De eenvoudigste strategie voor een nieuw project:

1. Zet alle gedeelde regels in AGENTS.md — 95% van de regels hoort daar.
2. Maak CLAUDE.md als je regels nodig hebt die alleen voor Claude gelden: zet @AGENTS.md op de eerste regel en voeg daaronder een sectie met Claude-specifieke regels toe. Als zulke regels ontbreken, is CLAUDE.md overbodig; Claude Code leest sinds versie 2.1.277 zelf AGENTS.md.
3. Behoud .cursor/rules/ voor Cursor voor zeldzame gevallen waarin iets specifiek voor Cursor nodig is (de opdrachten @Codebase en @Docs).
4. Doe hetzelfde voor Windsurf: vergeet het oude .windsurfrules; gebruik de nieuwe .windsurf/rules/ alleen als patronen voor de eigen syntaxis nodig zijn.

Met deze aanpak krijg je 80% van het voordeel voor 20% van het werk. Mijn ervaring is dat het onderhouden van meer dan twee bronnen van waarheid (gedeeld plus Claude-specifiek) lastig wordt wanneer ik gemengde teams in “Antigravity” organiseer. Als iemand in het team een regel aan .cursorrules toevoegt en AGENTS.md vergeet, zijn Cursor en Codex het een week later niet meer met elkaar eens.

Hoe haalt /init in Claude Code een bestaande AGENTS.md op?#

Anthropic beschrijft /init in de documentatie als volgt:

Wat betekent dit in de praktijk? De repository die ik beschreef had een .cursorrules uit de tijd dat ik Cursor probeerde (ongeveer 80 regels) en een handmatig samengestelde AGENTS.md (120 regels). Toen ik claude /init uitvoerde, nam de opdracht beide bestanden, verwijderde dubbele vergelijkbare regels en stelde binnen een minuut een nette CLAUDE.md samen. Ik controleerde die daarna en bracht kleine wijzigingen aan: verouderde items verwijderd en een structuur met koppen toegevoegd. Dat ging sneller dan helemaal opnieuw beginnen.

De interactieve modus, waarin /init ook AGENTS.md leest, wordt ingeschakeld met een omgevingsvariabele:

CLAUDE_CODE_NEW_INIT=1 claude

Nadat /init start, stelt Claude een reeks verduidelijkende vragen: welke artefacten moeten worden ingesteld (CLAUDE.md, skills, hooks), welke stack het project gebruikt en welke opdrachten je voor tests moet gebruiken. Daarna verkent een subagent de codebasis door package.json, README.md en configuratiebestanden te lezen en vult die ontbrekende onderdelen aan. Aan het einde toont die een voorstel dat je kunt bewerken voordat je het opslaat. Zie de aparte gids voor meer informatie over het configureren van Claude Code bij de start van een project.

En nu het nadeel. Als het project al een actieve AGENTS.md heeft, maakt /init daarnaast een CLAUDE.md met een kopie van de regels. Vanaf dat moment leest Claude Code standaard alleen CLAUDE.md, zodat er weer twee bronnen van waarheid zijn: jij werkt AGENTS.md bij, terwijl Claude de oude kopie blijft gebruiken. De opdracht /import doet iets vergelijkbaars: die voegt een eenmalige kopie van AGENTS.md aan CLAUDE.md toe. Zet de import @AGENTS.md na /init op de eerste regel van CLAUDE.md en verwijder daar alles wat AGENTS.md herhaalt om één bron te behouden.

/init is een goed startpunt voor een nieuw project of een project dat je van Cursor of Copilot overzet. Je hoeft online niet te zoeken naar het “beste CLAUDE.md-sjabloon” — Anthropic houdt al rekening met wat in de repository staat. Als een project al een actieve AGENTS.md heeft en er geen Claude-specifieke regels zijn, is /init overbodig: Claude Code leest AGENTS.md zelf.

Hoe scheid je gedeelde en Claude-specifieke instructies?#

Ik scheid ze volgens dit principe. Gedeelde regels voor AGENTS.md:

• Wat je niet mag aanraken in de code. De mappen .env, node_modules, prisma/migrations (alleen via prisma migrate), .next/, .git/.
• Hoe je dingen benoemt. Branches: feat/, fix/, chore/. Commits: de prefixes feat:, fix:, docs: plus een korte beschrijving. Componentbestanden in kebab-case.
• Test-/lintopdrachten. npm run build, npm run lint, npm test. Welke opdracht je vóór git push uitvoert.
• Architectuurprincipes. Wat in src/lib/ hoort, wat in src/components/, waar de bedrijfslogica staat en waar de UI staat.
• Beveiliging. Commit nooit geheimen. Benader de productiedatabase alleen via prod-psql. Benader productie via SSH alleen via de alias prod, niet via root@IP.

Claude-specifieke regels voor CLAUDE.md (onder @AGENTS.md):

• Plan mode. Gebruik plan mode voor wijzigingen in risicovolle mappen (bijvoorbeeld src/billing/).
• Effort-niveau. Gebruik --effort high voor architectuurtaken en medium voor routinewerk.
• Skills. Welke AI-agents en skills je in welke situaties uitvoert. Bijvoorbeeld: “voer de skill build-masterskaya-guide uit wanneer je aan een gids werkt.”
• Claude-geheugen. Wat je in automatisch geheugen zet en wat in CLAUDE.local.md. Zie de gids over Memory en CLAUDE.md voor meer informatie over Claude-geheugen.
• Hooks. Als .claude/settings.json hooks bevat, beschrijf dan in CLAUDE.md wat die doen (Codex en Cursor kennen ze niet en hoeven dat ook niet).
• Skills en opdrachten. Een lijst met slashopdrachten die ik vaak gebruik (/init, /cd, /memory, /plan).

De grens is niet altijd duidelijk. “Voer nooit git push --force uit naar main” is bijvoorbeeld duidelijk gedeeld en hoort dus in AGENTS.md. Maar “gebruik eerst plan mode als je git push naar een hot branch uitvoert” is specifiek voor Claude Code en hoort daarom in CLAUDE.md. De test: “Als ik Claude Code morgen verwijder en alleen Codex behoud, geldt deze regel dan nog steeds?” Zo ja, zet die in AGENTS.md. Zo nee, zet die in CLAUDE.md.

Wat hoort in AGENTS.md en wat in CLAUDE.md of .claude/rules?#

Als de regels meer dan 200 regels beslaan, is het tijd om ze op te splitsen. De documentatie van Anthropic raadt aan om ongeveer 200 regels per bestand aan te houden, omdat Claude lange CLAUDE.md-bestanden steeds minder trouw gaat volgen: het lijkt ze te lezen, maar houdt zich er minder vaak aan.

Een structuur voor een groot project die voor mij werkt:

my-project/
├── AGENTS.md                    # 100-150 lines, shared
├── CLAUDE.md                    # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
    ├── CLAUDE.md                # alternative to root file, same file
    └── rules/
        ├── api.md               # with paths: ['src/api/**']
        ├── components.md        # with paths: ['src/components/**']
        ├── testing.md           # without paths, always active
        └── security.md          # without paths, always active

Elk bestand in .claude/rules/ kan frontmatter hebben:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required

Claude laadt deze regels alleen wanneer het werkt met bestanden die overeenkomen met dit patroon. Als het src/components/Button.tsx aanpast, worden de API-regels niet aan de context toegevoegd. Zo wordt het contextvenster alleen gebruikt voor wat relevant is. De map .claude/rules/ werkt ook zonder CLAUDE.md: als het project alleen AGENTS.md bevat, worden de regels naast dat bestand geladen en schakelen ze het rechtstreeks lezen van AGENTS.md niet uit.

Cursor en Windsurf ondersteunen dezelfde aanpak via hun mappen .cursor/rules/ en .windsurf/rules/. De AGENTS.md-standaard kan naar deze mappen verwijzen, maar de syntaxis voor gebruik in meerdere tools is nog niet volledig stabiel. Het is veiliger om gedeelde regels in AGENTS.md te houden en padgebonden regels te dupliceren in .claude/rules/ en .cursor/rules/; dit zijn zeldzame specifieke gevallen, niet het grootste deel van de regels.

Handige locaties voor CLAUDE.md (van breed naar smal):

Een voorbeeld van ~/.claude/CLAUDE.md kan twee regels bevatten: “antwoord in de voorkeurstaal van de gebruiker” en “schrijf Ailoot precies zo.” Deze regels gelden voor elk project, dus je hoeft ze niet in elke repository te herhalen.

Van deze vier niveaus schakelen alleen een projectniveau-CLAUDE.md en CLAUDE.local.md het rechtstreeks lezen van AGENTS.md uit. Een persoonlijk ~/.claude/CLAUDE.md en beheerd beleid staan niet in de weg; Claude Code leest die naast AGENTS.md.

Wat moet je doen als AGENTS.md in je project al verouderd is?#

In het project dat ik beschreef, had ik een AGENTS.md uit mei 2025 — 180 regels, waarvan veel verouderd waren (het noemde Anthropic API-endpoints die sindsdien waren veranderd; voorbeelden met een claude --tools-syntaxis die niet meer bestaat; en regels over ~/.claude/projects/ met een verouderde structuur).

Het plan dat ik gebruikte om het bestand bij te werken:

1. Beoordeel het met claude in plan mode. Ik open de repository, voer claude --safe-mode uit en vraag: “Lees AGENTS.md opnieuw en stel een lijst voor van verouderde of herhaalde items. Bewerk het niet; geef alleen de lijst.” Binnen twee minuten kreeg ik een lijst van 23 items om te beoordelen.
2. Verwijder duidelijk verouderde items. Van de 23 items waren er 9 duidelijk verouderd — opdrachtsyntaxis, endpoints en flag-namen. Ik verwijderde die regels.
3. Voeg duplicaten samen. Nog eens 6 items herhaalden hetzelfde in andere bewoordingen (“force-push niet”, “gebruik --force nooit”, “vermijd git push -f”). Ik voegde ze samen tot één regel.
4. Voeg nieuwe items toe. Ik voegde dingen toe waarvan ik merkte dat Claude/Codex er de afgelopen maand regelmatig fouten mee maakte, volgens de regel “één regel per foutpatroon”. Dat leverde 8 nieuwe items op.
5. Voer een subagent uit voor een laatste beoordeling. Ik vroeg Claude om een beoordeling met de instructie “zoek tegenstrijdigheden, onduidelijkheden en duplicaten”. Claude vond drie formuleringen die duidelijker konden. Ik paste ze aan.

Na een uur telde AGENTS.md 110 regels, was het bijgewerkt en kende ik elke regel persoonlijk. Het was eenvoudig om er een CLAUDE.md van 30 regels op te baseren. Codex werd daarna merkbaar zorgvuldiger met tests — ik vermoed dat sommige “vreemde” beslissingen voortkwamen uit verouderde instructies die het te goeder trouw volgde.

De belangrijkste principes voor een levend AGENTS.md:

• Elke regel voorkomt een terugkerende fout. Als een regel me in de loop van de maand niet één keer te binnen schoot, heeft het geen zin die te bewaren.
• Schrijf regels als opdrachten, niet als theorie. “Gebruik twee spaties” is een regel. “De code moet er netjes uitzien” is dat niet.
• Specifiek gaat boven algemeen. “Voer npm run build uit vóór git push” is een regel. “Test je wijzigingen” is dat niet.

Wat werkt absoluut NIET met deze setup?#

Een paar dingen die ik tijdens zes maanden werken met deze setup op de harde manier heb geleerd:

1. Cursor-autocomplete gebruikt AGENTS.md niet. Wanneer Cursor voorstelt een regel in de editor af te maken, leest het AGENTS.md niet in realtime — daar is een aparte snelle engine voor. Regels in AGENTS.md zijn alleen van belang wanneer je in Cursor een chatverzoek doet. “Gebruik geen var, maar const” in AGENTS.md schrijven heeft dus geen invloed op autocomplete; daarvoor moet je ESLint of de TypeScript-configuratie instellen.

2. Claude Code-hooks in AGENTS.md werken niet voor Codex. Als .claude/settings.json een PreToolUse-hook heeft die is ingesteld om een bepaalde actie te blokkeren, is die informatie alleen nuttig voor Claude. Codex weet niets van hooks; voor Codex is het “de tool beslist zelf”. Het is verstandig om “doe X niet” in AGENTS.md te schrijven en “er is een hook die X fysiek blokkeert” in CLAUDE.md, onder de import.

3. Copilot en .github/copilot-instructions.md. GitHub Copilot leest zijn eigen bestand en leest AGENTS.md nog steeds niet erg goed. Als je team Copilot actief gebruikt, voeg dan een apart .github/copilot-instructions.md toe met een verkorte versie van de regels of gebruik Copilot Extensions die AGENTS.md begrijpen. Dit verandert snel, dus over drie tot zes maanden kan de situatie anders zijn.

4. Git houdt een symbolische link niet bij als een wijziging aan CLAUDE.md. Als je ln -s AGENTS.md CLAUDE.md uitvoert en een week later AGENTS.md bijwerkt, toont Git alleen een diff voor AGENTS.md. Dat is normaal, maar een collega die de PR beoordeelt, merkt misschien niet dat CLAUDE.md ook is bijgewerkt via de symbolische link. Oplossing: vermeld expliciet in de PR-beschrijving: “AGENTS.md bijgewerkt; Claude Code ziet hetzelfde bestand via de symbolische link.”

5. Diepe imports zijn moeilijk te debuggen. Als AGENTS.md @docs/coding-style.md importeert, dat op zijn beurt @docs/typescript.md importeert, en er regels met elkaar in conflict komen, is het moeilijk te achterhalen waar het probleem zit. Ik houd imports beperkt tot één niveau (CLAUDE.md → AGENTS.md) en nest ze niet verder. Anthropic biedt een InstructionsLoaded-hook die registreert welke bestanden zijn geladen — nuttig voor het debuggen van gelaagde setups. Let op: de hook wordt geactiveerd voor AGENTS.md dat via een import of symbolische link is opgenomen, maar niet voor AGENTS.md dat Claude Code zelf heeft gelezen.

De complete vibe-coding-setup voor een avond: AI-kloon + Tweede brein + contextengineering.

Maak kennis met Ailoot.