Wat is AGENTS.md en hoe gebruikt u het?

Wat AGENTS.md is

AGENTS.md is een eenvoudig Markdown-bestand in de root van een repository dat een coding agent vertelt hoe er aan dat project gewerkt moet worden. De officiële website omschrijft het als "een README voor agents: een toegewezen, voorspelbare plek om de context en instructies te bieden die AI-coding agents helpen bij het werken aan uw project." Het formaat wordt beheerd door de Agentic AI Foundation onder de Linux Foundation, en meer dan twintig agents lezen het, waaronder Codex, Cursor, Jules, Devin en GitHub Copilot (peildatum juli 2026).

De reden voor het bestaan van deze conventie is praktisch. Een nieuw teamlid leest de README, raadt het build-commando en vraagt iemand om hulp wanneer de gok onjuist is. Een agent kan niets vragen. Deze gokt, voert npm test uit op een project dat pnpm test gebruikt, leest de foutmelding en probeert iets anders. U betaalt voor elk van die tokens. Het eenmalig noteren van het juiste commando elimineert deze hele categorie van fouten.

Er zijn geen verplichte velden. De website is hier duidelijk over: "AGENTS.md is gewoon standaard Markdown. Gebruik welke koppen u maar wilt; de agent parseert simpelweg de tekst die u aanlevert." Dat is de volledige specificatie. De waarde zit niet in het formaat. De waarde zit in het feit dat het bestand op een pad staat waar elke tool al naar kijkt.

Waar het bestand wordt geplaatst en welk bestand voorrang krijgt

Plaats het eerste bestand in de root van de repository. In een monorepo kunt u er meer toevoegen in elk subproject. De regel is eenvoudig: "agents lezen automatisch het dichtstbijzijnde bestand in de mappenstructuur, dus het dichtstbijzijnde bestand krijgt voorrang." Een conflict tussen twee bestanden wordt opgelost ten gunste van het bestand dat wordt bewerkt, en alles wat u in de chat typt, overschrijft beide.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Het gebruik van geneste bestanden is aan te raden, omdat dit de enige manier is om regels te definiëren die in de ene map gelden en in de andere niet. Een regel zoals "elk endpoint valideert zijn invoer" hoort bij de endpoints zelf te staan. In een root-bestand wordt deze bij elke irrelevante taak geladen, wat geen voordeel oplevert. Als uw root-bestand al is gegroeid naar een sectie per service, is het opsplitsen naar een geneste structuur de oplossing. Dit bepaalt welke regels naar beneden verhuizen en welke bovenaan blijven staan.

Wat hoort er in een AGENTS.md

Noteer wat een agent niet kan afleiden uit het lezen van de code. De exacte build-, test- en lint-commando's staan bovenaan, in de vorm zoals u ze in een terminal zou plakken. Voeg het commando toe voor het uitvoeren van één enkele test; een agent die alleen weet hoe de volledige suite moet worden gedraaid, zal deze anders veertig keer uitvoeren. Benoem de conventies die afwijken van de standaardinstellingen van de tool, aangezien de agent de standaard al kent en alleen hoeft te weten waar u hiervan afwijkt. Voeg de structuur voor commit-berichten en de regels voor pull requests toe als u deze hanteert.

Wees concreet genoeg zodat een bewering kan worden gecontroleerd. "Gebruik een inspringing van 2 spaties" is een bruikbare instructie omdat dit ofwel is gebeurd, of niet. "Formatteer code correct" is dat niet, omdat hierin niets verifieerbaar is. Hetzelfde geldt voor locaties: "API-handlers staan in src/api/handlers/" is beter dan "houd bestanden georganiseerd".

Negatieve regels zijn ook waardevol. "Bewerk nooit bestanden onder dist/, deze worden gegenereerd door npm run build" voorkomt een specifieke fout, en omdat de oorzaak wordt benoemd, kan de agent vergelijkbare gevallen afleiden die u niet expliciet heeft opgeschreven. Een regel over de scope hoort hier ook thuis, omdat een agent die op eigen oordeel vertrouwt, meer zal herschrijven dan u heeft gevraagd: één veelgekopieerde vaardigheid doet niets anders dan aandringen op de kleinst mogelijke wijziging die werkt.

Wat hier nooit in thuishoort

Plaats nooit een geheim in een van deze bestanden. Het bestand wordt gecommit naar git, bij de start van elke sessie in de context geladen en bij elk verzoek naar een modelprovider verzonden. Een API key in een AGENTS.md is een API key in uw repository-geschiedenis en in de logs van een derde partij. Verwijs naar het geheim in plaats van het te plakken: "het databasewachtwoord staat in .env, dat is genegeerd door git; vraag om toestemming voordat u het leest." De bredere discipline wordt behandeld in het buiten bereik houden van inloggegevens voor een agent.

Laat alles weg wat de agent zelf kan afleiden door te kijken. Een geplakte mappenlijst, een kopie van uw afhankelijkhedenlijst, een architectuuroverzicht dat de mapnamen herhaalt: dit alles veroudert al een week nadat u het heeft geschreven en kost ondertussen bij elke sessie context. Behoud de valkuilen en de redenen. Laat de inventaris weg. De redenen zijn het waard om apart te houden, omdat een agent die niet kan zien waarom een ongebruikelijke structuur bestaat, deze stilletjes zal wegrefactoren. Dit is de reden voor het bijhouden van een DESIGN.md naast dit bestand.

CLAUDE.md is de Claude Code-instantie van hetzelfde concept

Claude Code leest CLAUDE.md en leest AGENTS.md niet uit zichzelf. Een projectbestand bevindt zich op ./CLAUDE.md of ./.claude/CLAUDE.md, persoonlijke voorkeuren voor elk project staan in ~/.claude/CLAUDE.md, en een organisatie kan een machinebreed bestand pushen naar /etc/claude-code/CLAUDE.md op Linux. Gevonden bestanden worden samengevoegd vanaf de root van het bestandssysteem tot aan uw werkmap, waardoor het bestand dat het dichtst bij de locatie waar u de sessie startte staat, als laatste wordt gelezen. Elke sessie die u in die map start, laadt dezelfde stack; dit maakt het werkbaar om er twee naast elkaar op één machine te draaien, en die sessies kunnen werk aan elkaar overdragen terwijl ze draaien.

Als uw repository al een AGENTS.md heeft, onderhoud dan geen tweede kopie. Importeer deze en voeg alleen toe wat specifiek is voor Claude:

@AGENTS.md

## Claude Code

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

Een symlink werkt wanneer u niets extra's toe te voegen heeft:

ln -s AGENTS.md CLAUDE.md

Het commando geeft bij succes niets weer. Voer in uw volgende sessie /context uit en bevestig dat CLAUDE.md verschijnt onder Memory files. Als het ontbreekt in die lijst, is het bestand nooit geladen en is er dus niets uit toegepast. Om een eerste concept te genereren in plaats van er zelf een te schrijven, voert u /init uit: dit leest de codebase en produceert een startbestand. Wanneer er al een CLAUDE.md bestaat, stelt het verbeteringen voor in plaats van het te overschrijven.

Houd elk bestand onder ongeveer 200 regels. Langere bestanden verbruiken meer van het venster en de naleving neemt af. Als u wilt zien wat er nog meer strijdt om die ruimte, legt wat daadwerkelijk het contextvenster van een agent vult dit in detail uit.

Eén punt verdient extra aandacht. Een AGENTS.md is een richtlijn, geen permissiesysteem. De inhoud komt binnen als gewone context, dus het model leest het en volgt het doorgaans op, maar niets blokkeert een actie die hiermee in strijd is. Wanneer een regel die u heeft geschreven stilletjes wordt overgeslagen en u niet kunt achterhalen waarom, doorloop dan de redenen waarom een instructie wordt genegeerd voordat u de formulering voor de derde keer herschrijft. Gebruik voor een regel die elke keer moet gelden, zoals "push nooit naar main", een hook of een permissie-instelling, omdat die als code worden uitgevoerd en niet afhankelijk zijn van de beslissing van het model om te gehoorzamen.

Tools die deze bestanden voor u schrijven

Twee projecten op de GitHub trending-lijst van 30 juli 2026 laten zien waar de conventie naartoe gaat.

agent0ai/dox (1.368 sterren per juli 2026) is een framework om een boomstructuur van AGENTS.md-bestanden actueel te houden. Het levert geen package en geen runtime. U kopieert de inhoud van de AGENTS.md naar uw eigen root AGENTS.md, en dat is de installatie. Voor een bestaand project geeft u uw agent de volgende instructie:

Initialize DOX tree for this project now.

De agent maakt vervolgens de onderliggende AGENTS.md-bestanden en hun indexen aan, doorloopt de boomstructuur voordat er iets wordt gewijzigd, en werkt de betreffende documentatie bij nadat een wijziging is doorgevoerd. De gedachte hierachter is dat documentatie die een agent als bijproduct van zijn werk onderhoudt, accuraat blijft, terwijl documentatie die handmatig door een persoon wordt bijgewerkt, dat niet doet.

HUMAN.md, dezelfde truc toegepast op uzelf

Intuition-Lab/personal-model (1.260 sterren per juli 2026) past dit patroon toe op een persoon in plaats van op een repository. Het project presenteert uw HUMAN.md als de output van het systeem in plaats van als een bestand dat u zelf typt: "een levend model van wat er nu toe doet, hoe u doorgaans beslist en waar uw aandacht naartoe gaat." Het draait lokaal op macOS 13 of hoger, registreert activiteit nadat u macOS-toestemming heeft verleend en stelt het resultaat beschikbaar aan agents via MCP (model context protocol). Het korte installatiepad:

uv tool install personal-model
persome onboard
persome model open --after 30

U heeft dit alles niet nodig om het meeste voordeel te behalen. Een handgeschreven HUMAN.md beslaat ongeveer twintig regels: uw rol, uw tijdzone, de stack die u daadwerkelijk gebruikt, de beslissingen die u al heeft genomen en niet opnieuw wilt openen, en hoeveel uitleg u terug wilt ontvangen. Het bespaart hetzelfde herhaalde uitleggen als een projectbestand, maar dan één niveau hoger.

Eén waarschuwing. Een HUMAN.md is een profiel van een persoon en is daarom per definitie gevoelig. Houd het uit een publieke repository. Plaats het in ~/.claude/CLAUDE.md, of in een door git genegeerd CLAUDE.local.md in de hoofdmap van het project, dat samen met het gecommitteerde bestand wordt geladen en op dezelfde manier wordt behandeld.

Een startsjabloon dat u kunt kopiëren

Dit is bewust kort gehouden. Verwijder de secties die niet van toepassing zijn en weersta de verleiding om secties toe te voegen die u niet actueel kunt houden.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Schrijf het en corrigeer het vervolgens op de plek zelf. Het signaal om een regel toe te voegen is dat u dezelfde correctie twee keer in de chat hebt getypt. Die ene regel houdt het bestand bruikbaar en voorkomt dat het bestand uitgroeit tot een document dat niemand leest, machines inbegrepen. Zodra het stabiel is, reist het mee met de repository. Dit is vooral van belang wanneer de agent ergens anders draait dan op uw laptop: het draaien van een coding agent op uw eigen server behandelt die configuratie.

FAQ

Is AGENTS.md hetzelfde bestand als CLAUDE.md?

Het is hetzelfde concept onder twee verschillende bestandsnamen. Claude Code leest CLAUDE.md en negeert AGENTS.md, tenzij u ze koppelt. Houd één bestand aan als de bron van waarheid en verwijs vanuit het andere bestand hiernaar, ofwel met een regel die @AGENTS.md bevat bovenaan uw CLAUDE.md, of met ln -s AGENTS.md CLAUDE.md. Twee volledige kopieën die afzonderlijk worden bijgehouden, zullen binnen een maand van elkaar gaan afwijken.

Garandeert het schrijven van een AGENTS.md dat de agent deze opvolgt?

Nee. De inhoud wordt aangeleverd als context, waardoor het model deze leest en doorgaans naleeft, maar niets blokkeert een actie die hiermee in strijd is. Vage instructies worden het minst betrouwbaar opgevolgd, en twee bestanden met tegenstrijdige richtlijnen laten de agent willekeurig een keuze maken. Gebruik voor een regel die altijd moet gelden een hook of een toegangsregel; deze worden door de client afgedwongen, ongeacht wat het model besluit.

Moet AGENTS.md worden toegevoegd aan git?

Ja, voor alles wat waar is over het project: build-commando's, structuur en conventies. Dat is het doel van het bestand, omdat de agents van uw teamgenoten dan met dezelfde context beginnen als die van u. Alles wat persoonlijk is of specifiek voor één machine, hoort thuis in een apart bestand dat in gitignore staat, en inloggegevens horen in geen van beide thuis.

Wat is HUMAN.md en heb ik er een nodig?

HUMAN.md is een machineleesbaar profiel van een persoon in plaats van een project. Het bevat uw rol, uw beperkingen en de beslissingen die u al heeft genomen, zodat deze niet elke sessie opnieuw hoeven te worden besproken. U heeft geen extra tools nodig om te beginnen: twintig handgeschreven regels in uw instructiebestand op gebruikersniveau bieden u het meeste nut. Behandel dit als persoonlijke gegevens en houd het buiten elk repository dat u pusht.