# Eén instructiebestand voor Claude Code, Codex en Cursor in 2026
> Eén bron van waarheid voor Claude Code, Codex en Cursor in 2026: wanneer Claude Code AGENTS.md zelf leest, @AGENTS.md importeren in CLAUDE.md, een symbolische link en /init.
Source: https://ailoot.ai/blog/nl/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/nl/agents-md-claude-md-one-instruction-file/
Language: nl
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-f1ff623d0863230de3156e2670dd93cc1caee6aac01d09aa094e7c5c70011bb8
Zie de [Ailoot-documentatie](https://ailoot.ai/docs/) voor informatie over de service.
## Wat verandert er als je Claude Code, Codex en Cursor samen gebruikt?
Belangrijkste punt
In 2026 bestaat de gebruikelijke setup van een vibe coder niet uit één tool, maar uit 3–5. Claude Code als hoofdtool, Codex voor lange autonome taken, Cursor voor snelle bewerkingen in de IDE. Elk heeft een eigen instructiebestand: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Als je ze handmatig gesynchroniseerd houdt, bewerk je één regel op vijf plekken, vergeet je Cursor bij te werken en geven Claude en Codex een week later verschillende resultaten voor dezelfde prompt.
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](https://ailoot.ai/blog/nl/claude-code-codex-together/).
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?
Belangrijkste punt
Ja, vanaf versie 2.1.277, uitgebracht op 18 september 2026, maar alleen als er geen `CLAUDE.md`, `.claude/CLAUDE.md` of `CLAUDE.local.md` in de werkmap of een bovenliggende map staat. Als `CLAUDE.md` bestaat, leest Claude Code standaard alleen dat bestand en wordt `AGENTS.md` opgenomen met de regel `@AGENTS.md` in `CLAUDE.md` of met een symbolische link. Je kunt dit gedrag wijzigen in `/config`, onder Project instructions. Vóór september las Claude Code `AGENTS.md` helemaal niet en was importeren de enige manier.
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:
Claude Code kan AGENTS.md lezen als projectinstructies, zodat een repository die al voor andere agents is ingesteld zonder CLAUDE.md, import of configuratie werkt.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Welke bestanden Claude Code precies leest, hangt af van de bestanden in het project:
| Bestanden in het project | Wat Claude Code leest |
|----|----|
| `AGENTS.md`, zonder `CLAUDE.md` of `CLAUDE.local.md` in de werkmap of een bovenliggende map | `AGENTS.md` |
| `AGENTS.md` en `CLAUDE.md` (of `CLAUDE.local.md`) in de werkmap of een bovenliggende map | Alleen `CLAUDE.md` |
| `CLAUDE.md` met de regel `@AGENTS.md` | `CLAUDE.md` en `AGENTS.md` daarin via de import |
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:
| Instelling | Wat Claude Code leest |
|----|----|
| `claude-md-or-agents-md` (standaard) | `CLAUDE.md`, of, als noch dat bestand noch `CLAUDE.local.md` bestaat, `AGENTS.md` |
| `claude-md-and-agents-md` | Beide bestanden: in elke map eerst `CLAUDE.md`, daarna `AGENTS.md` |
| `claude-md` | Alleen `CLAUDE.md` |
| `managed-only` | Alleen de door het bedrijf beheerde `CLAUDE.md` en automatisch geheugen |
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?
Belangrijkste punt
Een import is nodig wanneer het project een `CLAUDE.md` heeft: als dat bestand aanwezig is, leest Claude Code `AGENTS.md` standaard niet zelf. Stel het in door bovenaan het bestand `CLAUDE.md` de regel `@AGENTS.md` te zetten. Wanneer Claude Code een sessie start, plaatst het de inhoud van `AGENTS.md` op de plek van die regel en leest het resultaat als één tekst. Onder de import kun je een sectie “Claude Code” toevoegen met regels die alleen voor Claude gelden. Imports werken met relatieve en absolute paden en kunnen maximaal vier niveaus diep genest zijn.
Een minimaal werkend voorbeeld uit de officiële documentatie:
```markdown
@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:
CLAUDE.md-bestanden kunnen extra bestanden importeren met de syntaxis @path/to/import. Geïmporteerde bestanden worden uitgevouwen en bij het opstarten van een sessie in de context geladen, samen met het CLAUDE.md-bestand dat ernaar verwijst.
— Anthropic, https://code.claude.com/docs/en/memory
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?
Belangrijkste punt
Anthropic biedt twee mechanismen: een import via `@AGENTS.md` of een symbolische link, `ln -s AGENTS.md CLAUDE.md`. Een symbolische link is eenvoudiger: het is alleen een alias en vereist geen bestandswijzigingen. Maar er zijn drie nadelen: Windows vereist beheerdersrechten, je kunt geen Claude-specifieke regels aan `CLAUDE.md` toevoegen en Git toont een symbolische link soms als rommel in de diff. Importeren is de universele aanpak. Als je geen regels hebt die alleen voor Claude gelden, heb je vanaf versie 2.1.277 geen van beide nodig: Claude Code leest `AGENTS.md` zelf.
De documentatie toont de optie met een symbolische link als volgt:
```bash
ln -s AGENTS.md CLAUDE.md
```
Daarna volgt meteen een openhartige waarschuwing over Windows:
Als jij of iemand die de repository kloont op Windows werkt, gebruik dan de import `@AGENTS.md`. Daar is voor het maken van een symbolische link beheerdersrechten of Developer Mode vereist. En Git zonder ingeschakelde `core.symlinks` haalt een gecommitte link binnen als een gewoon tekstbestand, waardoor er in die kopie een `CLAUDE.md` van één regel staat in plaats van de instructies.
— Anthropic, https://code.claude.com/docs/en/memory
Vergelijkingstabel:
| Criterium | Import `@AGENTS.md` | Symbolische link `ln -s` |
|----|----|----|
| **Werkt op Windows zonder beheerdersrechten** | ja | nee (Developer Mode vereist) |
| **Regels toevoegen die alleen voor Claude gelden** | ja, onder de import | nee, het bestand is identiek |
| **Verschijnt in Git als gewone markdown** | ja | als link (afhankelijk van `core.symlinks`) |
| **Kan meerdere bestanden importeren** | ja, maximaal vier niveaus diep | nee, één-op-één |
| **Caching/invalidation in Claude Code** | standaard voor CLAUDE.md | werkt, maar symbolische links hebben valkuilen met metadata |
| **Standaardkeuze** | geschikt voor iedereen | alleen als cross-platformgebruik niet belangrijk is |
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](https://ailoot.ai/blog/nl/claude-code-safe-mode-recovery/) 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?
Belangrijkste punt
Elke tool leest zijn eigen bestand, soms meer dan één. Claude Code leest `CLAUDE.md` en leest sinds september 2026 ook `AGENTS.md` als het project geen `CLAUDE.md` heeft. Codex CLI leest `AGENTS.md` plus `AGENTS.override.md`. Cursor leest het oudere formaat `.cursorrules` of de nieuwere `.cursor/rules/*.mdc`, en leest sinds de zomer van 2026 ook `AGENTS.md`. Copilot leest `.github/copilot-instructions.md` of `.github/instructions/*.instructions.md`. Windsurf leest het oudere `.windsurfrules` of het nieuwere `.windsurf/rules/`. Gemini CLI leest `GEMINI.md`. Aider en Cline hebben `AGENTS.md` al overgenomen.
Een overzicht van de zeven belangrijkste tools (gebaseerd op de officiële documentatie van elke tool):
| Tool | Hoofdinstructiebestand | Alternatieven | Leest het AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, beheerd beleid | ja, als het project geen `CLAUDE.md` heeft (sinds 2.1.277), anders via een import |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | ja (native) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (verouderd) | ja |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | via extensies |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (verouderd) | ja |
| **Gemini CLI** | `GEMINI.md` | \- | nee |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | ja (native) |
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?
Belangrijkste punt
`/init` bouwt op basis van wat al in de repository staat een `CLAUDE.md` en bespaart 20–30 minuten handwerk. Standaard neemt het Cursor-regels (`.cursor/rules/`, `.cursorrules`) en Copilot-regels (`.github/copilot-instructions.md`) over; in de modus `CLAUDE_CODE_NEW_INIT=1` leest het `AGENTS.md`, `.windsurfrules` en `.clinerules`. Deze modus start ook een interactief proces in meerdere fasen: het stelt vragen, verkent de code met een subagent en doet een voorstel voordat het gaat schrijven. Sinds september 2026 heeft `/init` een nadeel in een project met `AGENTS.md`: een nieuw `CLAUDE.md` schakelt het rechtstreeks lezen van `AGENTS.md` uit, waardoor de regels in twee bestanden terechtkomen.
Anthropic beschrijft `/init` in de documentatie als volgt:
Als je /init uitvoert, worden de instructiebestanden van andere tools gelezen en relevante onderdelen naar de gegenereerde CLAUDE.md verplaatst: Cursor-regels uit `.cursor/rules/` of `.cursorrules`, Copilot-regels uit `.github/copilot-instructions.md` en, met CLAUDE_CODE_NEW_INIT=1, ook `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` of `.windsurfrules`, en `.clinerules`.
— Anthropic, https://code.claude.com/docs/en/memory
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:
```bash
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](https://ailoot.ai/blog/nl/spec-kit-claude-code-spec-driven-development/) 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?
Belangrijkste punt
Zet regels die elke AI-agent kan begrijpen in `AGENTS.md`: wat je niet mag aanraken, hoe je branches benoemt, dat `.env` een geheim bevat en welke opdrachten je voor tests gebruikt. Zet regels die specifiek zijn voor Claude Code in `CLAUDE.md` (onder de import): plan mode, skills, hooks, verwijzingen naar skills en modelnamen per versie. Het onderscheid is eenvoudig: als een regel begint met “Claude moet”, hoort die in `CLAUDE.md`. Begint die met “de tool moet”, dan hoort die in `AGENTS.md`.
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](https://ailoot.ai/blog/nl/claude-memory-claude-md-auto-memory/) 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?
Belangrijkste punt
Voor een groot project is één `AGENTS.md` niet genoeg: het bestand wordt te groot en elke agent krijgt onnodig materiaal in zijn context. De oplossing is een map `.claude/rules/` met aparte bestanden per onderwerp en YAML-frontmatter `paths:` voor triggers op basis van paden. Een API-regel geldt bijvoorbeeld alleen wanneer Claude in `src/api/` werkt. Dat bespaart veel ruimte in het contextvenster. Het equivalent voor Cursor is `.cursor/rules/` en voor Windsurf `.windsurf/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:
```markdown
---
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):
| Niveau | Locatie | Doel |
|----|----|----|
| **Beheerd beleid** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Bedrijfsregels, IT/DevOps |
| **Gebruiker** | `~/.claude/CLAUDE.md` | Persoonlijke voorkeuren voor alle projecten |
| **Project** | `./CLAUDE.md` of `./.claude/CLAUDE.md` | Regels voor het projectteam |
| **Lokaal** | `./CLAUDE.local.md` (in `.gitignore`) | Persoonlijke voorkeuren voor een specifiek project |
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?
Belangrijkste punt
Als `AGENTS.md` in 2025 voor Codex of Aider is samengesteld en sindsdien niet is bewerkt, open dan het project in Claude Code en vraag Claude het bestand te bewerken. AGENTS.md is een levend document; de specificatie van de Linux Foundation wordt bijgewerkt. De hoofdregel om het actueel te houden: elke regel moet antwoord geven op de vraag “Wat ben ik het zat om steeds opnieuw aan Claude/Codex te vertellen?” Als dat niet zo is, archiveer de regel.
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?
Belangrijkste punt
`@AGENTS.md` importeren zorgt er niet voor dat verschillende tools zich hetzelfde gedragen. Elk heeft eigen eigenaardigheden: Codex CLI kent `.claude/rules/` of hooks niet. Cursor heeft een eigen engine voor automatisch aanvullen, die tijdens het aanvullen van tekst CLAUDE.md niet leest. Copilot volgt `.github/copilot-instructions.md`; alleen regels in AGENTS.md zijn voor Copilot niet genoeg. Het is niet “één bestand = één gedrag”, maar “één bron voor de basisregels, met aanvullingen per tool”.
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](https://github.com/marketplace?type=apps&category=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.
### Bronnen
- [Claude Code Memory-documentatie - sectie AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) - wanneer Claude Code AGENTS.md zelf leest, Project instructions-instellingen, imports en symbolische links, en het gedrag van `/init`.
- [Claude Code Memory-documentatie - extra bestanden importeren](https://code.claude.com/docs/en/memory#import-additional-files) - syntaxis `@path/to/file`, diepte van vier niveaus, relatieve en absolute paden.
- [agents.md - standaard van de Linux Foundation](https://agents.md/) - officiële AGENTS.md-standaard en lijst met ondersteunde tools.
- [Cursor Rules-documentatie](https://docs.cursor.com/context/rules-for-ai) - wat Cursor leest (`.cursor/rules/*.mdc`, AGENTS.md).
- [Aangepaste instructies voor GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) - formaat van `.github/copilot-instructions.md`.
- [AGENTS.md-specificatie bij de Linux Foundation](https://aaif.io/projects/agents-md/) - levende specificatie.
De complete vibe-coding-setup voor een avond: **AI-kloon + Tweede brein + contextengineering**.
Maak kennis met [Ailoot](https://ailoot.ai/).
## Vragen en antwoorden
### Wanneer gebruik ik een import in plaats van een symbolische koppeling?
Gebruik @AGENTS.md in CLAUDE.md wanneer je Claude-specifieke aanvullingen nodig hebt of teamgenoten Windows gebruiken. Een symbolische koppeling laat beide namen naar dezelfde inhoud verwijzen en kan dus geen apart Claude-gedeelte bevatten.
### Hoe controleer ik of gedeelde instructies zijn geladen?
Voer /memory uit en bekijk de vermelde instructiebestanden. Onderdrukt CLAUDE.md of CLAUDE.local.md in jouw configuratie direct laden van AGENTS.md, voeg dan de import toe of kies de instelling die beide laadt en begin daarna een verse sessie.
## Ailoot · Het bedrijf en zijn projectenportefeuille
Ailoot bouwt op opgebouwde operationele ervaring, een groot klantenbestand, een stabiele dienst en doorlopende KPI-controle.
Het bedrijf en zijn projectenportefeuille: miljoenen klanten; maandelijkse verkopen in de miljarden.
Ailoot gebruikt die operationele ervaring voor API-toegang tot AI-functies in klantproducten, agents, applicaties en automatiseringen.