Wat het bestand is
CLAUDE.md (voor Claude Code) en AGENTS.md (voor Codex, Cursor, GitHub Copilot’s coding agent, Gemini CLI en tientallen andere tools) zijn gewone Markdown-bestanden die een coding agent bij de start van een sessie inlaadt. De site agents.md noemt het “een README voor agents”. Wat erin staat, staat in elke sessie in het contextvenster. Dat is meteen de reden om er streng in te zijn: elke regel kost context, in elke sessie, voor iedereen in het team.
Wat erin hoort
De documentatie van Claude Code zegt het kort: zet erin “wat je anders opnieuw zou uitleggen”, en beperk je tot feiten die Claude in elke sessie nodig heeft. Agents.md noemt dezelfde soort inhoud.
| Hoort erin | Voorbeeld |
|---|---|
| Bouw- en testcommando’s | “Draai npm test voor je commit” |
| Conventies die je niet uit de code kunt aflezen | “Datums altijd in UTC opslaan, pas in de interface omzetten” |
| Waar wat staat | “API-handlers staan in src/api/handlers/” |
| Vaste regels | “Geen nieuwe dependency zonder overleg in het teamkanaal” |
| Valkuilen die al eens misgingen | “De testdatabase heeft een lokale Redis nodig” |
| Hoe je oplevert | Commitstijl, pull requests, wie reviewt |
Maak zinnen toetsbaar. Anthropic geeft zelf de voorbeelden: “Gebruik 2 spaties inspringing” in plaats van “Formatteer de code netjes”, “Draai npm test voor je commit” in plaats van “Test je wijzigingen”. En geef de reden erbij waar die niet vanzelf spreekt: een model dat weet waarom een regel bestaat, past hem beter toe in gevallen die je niet voorzag.
Wat er niet in hoort
- Procedures van meerdere stappen die maar soms nodig zijn. Zet die in een skill; die laadt pas als de taak erom vraagt.
- Regels voor één deel van de code. In Claude Code gaan die in
.claude/rules/met eenpaths-veld, zodat ze alleen laden bij die bestanden. In Codex zet je een eigen AGENTS.md in de submap; het dichtstbijzijnde bestand weegt het zwaarst. - Geheimen. Sleutels en wachtwoorden horen niet in een bestand dat in git staat en in elke sessie in de context komt.
- Feiten die snel veranderen. Een prijslijst, de huidige sprint, de stand van een klant. Die zijn morgen fout en niemand haalt ze eruit.
- Wat de agent zelf uit de code kan halen. Een lijst van alle bestanden of een samenvatting van elke module kost context en veroudert.
- Persoonlijke voorkeuren. Die gaan in
CLAUDE.local.md(niet in git) of in je eigen~/.claude/CLAUDE.md.
Houd het kort en houd het bij
Anthropic adviseert onder de 200 regels per CLAUDE.md: langere bestanden “kosten meer context en verminderen de opvolging”. Imports met @pad helpen om een lang bestand te ordenen, maar besparen geen context, want het geïmporteerde bestand laadt mee. Codex stopt standaard met inladen als de AGENTS.md-bestanden samen 32 KiB bereiken; wat daarna komt, ziet de agent niet.
Tegenstrijdige regels zijn het tweede probleem. Volgens de documentatie kiest Claude bij twee botsende instructies “mogelijk willekeurig” één. Claude Code heeft daarvoor /doctor prompt-audit, dat je instructiebestanden nakijkt op verouderde verwijzingen en tegenspraak, en alleen voorstellen doet.
Het misverstand: wat erin staat, gebeurt ook
CLAUDE.md en AGENTS.md zijn context, geen slot op de deur. Claude Code behandelt ze volgens de eigen documentatie “als context, niet als afgedwongen configuratie”. Wil je dat iets echt niet gebeurt, zoals pushen naar main of een bestand met sleutels lezen, dan blokkeer je dat met een hook of met rechten in de instellingen. Zie Wat zijn hooks in Claude Code?
Eén bestand voor alle tools
Gebruikt je team zowel Claude Code als Codex of Cursor, houd dan één bron bij. Vanaf versie 2.1.277 leest Claude Code standaard AGENTS.md als er in de werkmap of de mappen erboven geen CLAUDE.md, .claude/CLAUDE.md of CLAUDE.local.md staat. Heb je toch een CLAUDE.md nodig, zet dan @AGENTS.md erin en daaronder alleen wat specifiek voor Claude is. Zo leest elke tool dezelfde basis. Hoe Codex het bestand leest staat in Wat is AGENTS.md en hoe leest Codex dat bestand?
Wat dit voor een team betekent
Het bestand werkt alleen voor wie in die repository werkt. De kennis erin bereikt de product owner in ChatGPT niet, en de ontwikkelaar in een andere repository ook niet. En de lessen die een agent tijdens het werk leert, belanden in het persoonlijke geheugen van één ontwikkelaar, niet in het gedeelde bestand, tenzij iemand ze daar bewust in zet.
Waar Bombos past
Bombos houdt de kennis bij die niet in één repo past: teamafspraken, geleerde regels die gelden voor een klant of een deel van het werk, en wat er al in mail, documenten en andere repo’s staat. Elke AI-tool van het team, van Claude Code, Codex en Cursor tot ChatGPT en Copilot, leest daaruit via de plugin, en je ziet waarop een antwoord rust. AGENTS.md blijft de plek voor de vaste basis van één repo. Eén ontwikkelaar kan het eerst zelf proberen.
Vragen die hierbij horen
Leest Claude Code ook AGENTS.md?
Ja. Vanaf versie 2.1.277 leest Claude Code standaard AGENTS.md als er in de werkmap of de mappen erboven geen CLAUDE.md, .claude/CLAUDE.md of CLAUDE.local.md staat. Heb je toch een CLAUDE.md, zet dan @AGENTS.md bovenaan, zodat alle tools dezelfde basis lezen.
Hoe lang mag zo'n bestand zijn?
Anthropic adviseert onder de 200 regels per CLAUDE.md, omdat langere bestanden meer context kosten en slechter worden opgevolgd. Codex stopt standaard met inladen bij 32 KiB aan AGENTS.md-bestanden samen.
Wanneer voeg ik iets toe?
Als de agent dezelfde fout voor de tweede keer maakt, als een code review iets vindt wat hij had moeten weten, of als je dezelfde correctie in de chat typt als vorige keer. Zo noemt de documentatie van Claude Code het.
Wordt alles wat erin staat ook opgevolgd?
Niet gegarandeerd. Claude Code behandelt CLAUDE.md als context, niet als afgedwongen configuratie. Wat echt niet mag, blokkeer je met een hook of met rechten in de instellingen.
