Agent-instructiebestand (AGENTS.md, llms.txt)

Wat is een agent-instructiebestand?

Een agent-instructiebestand is een gewoon tekstbestand, meestal in Markdown, dat je neerzet waar een AI-agent het vindt, zodat de agent weet hoe hij zich daar moet gedragen. In een coderepository staat erin hoe je het project bouwt en test, welke afspraken gelden en waar de agent van moet afblijven. Op een website staat erin wat de site is, welke pagina's ertoe doen en waar de machineleesbare endpoints zitten. De agent leest het bestand voor hij begint, en een mens kan het net zo goed lezen.

Er bestaan twee families, en ze lossen twee verschillende problemen op.

Instructiebestanden in een repository zijn er voor coding agents. AGENTS.md is de open standaard: OpenAI bracht het in augustus 2025 uit, en sinds december 2025 zit het bij de Agentic AI Foundation onder de Linux Foundation, samen met MCP. De site agents.md telt meer dan 60.000 open source-projecten die er een gebruiken. Claude Code leest CLAUDE.md, Cursor leest zijn map .cursor/rules, GitHub Copilot leest .github/copilot-instructions.md, en alle drie lezen of importeren ze ook AGENTS.md. Eén bestand kan dus het hele team bedienen, welke tool iemand ook gebruikt.

Bestanden op siteniveau zijn er voor agents die je website bezoeken. Het voorstel llms.txt van Jeremy Howard, gepubliceerd in september 2024, beschrijft een kort Markdown-bestand in de root van een domein met een titel, een samenvatting van één alinea en lijsten met links naar de pagina's die het lezen waard zijn. In mei 2026 begon Shopify standaard een /agents.md te serveren op elke winkel, met /llms.txt dat naar dezelfde inhoud wijst. Dat is tot nu toe de grootste uitrol van het idee. De oudere neef is robots.txt, dat crawlers sinds de jaren negentig vertelt welke delen van een site ze mogen ophalen.

Het kortste beeld: een README die voor de agent geschreven is in plaats van voor de nieuwe collega. Het staat naast het werk, het zit mee in versiebeheer, en wie het werk beheert, onderhoudt het.

Hoe de twee families werken

In een repository

Elke coding agent loopt de mappenstructuur af op zoek naar zijn bestand. Codex begint bij de root van het project en loopt naar beneden tot de map waarin je werkt. Elke AGENTS.md die hij tegenkomt plakt hij erbij, dus een bestand in services/payments/ vult het bestand in de root aan en wint waar ze elkaar tegenspreken. Claude Code doet hetzelfde met CLAUDE.md en laadt bestanden in submappen pas als hij in die mappen aan het werk gaat. De praktische regel staat op de site agents.md: het dichtstbijzijnde bestand krijgt voorrang.

Op een website

Een llms.txt heeft een vaste vorm. Eén H1 met de naam van de site, een blockquote met een samenvatting, en dan H2-secties met links en bij elke link een korte toelichting. Een sectie met de naam Optional bevat links die een agent mag overslaan als hij weinig plaats heeft. Anthropic publiceert er een voor de documentatie van Claude Code.

De standaard /agents.md van Shopify gaat een stap verder. Daarin staan het MCP-endpoint en de UCP-discovery-URL van de winkel, alleen-lezen URL's voor producten, collecties en zoeken, en de gepubliceerde winkelvoorwaarden. Een shopping agent vindt zo wat hij nodig heeft zonder het thema te moeten scrapen. Sinds 28 mei 2026 kan een handelaar het vervangen door een eigen Liquid-template.

Het verschil met robots.txt zit in waarvoor elk bestand dient. Robots.txt, gestandaardiseerd als RFC 9309, zegt welke delen van een site een geautomatiseerde client mag ophalen, en zelfs dat is een verzoek en geen toegangscontrole. Llms.txt zegt niets over toestemming; het zegt waar het nuttige materiaal staat.

Wat hoort erin en wat niet?

Een goed repositorybestand is kort en concreet. De richtlijn van Anthropic voor CLAUDE.md is onder de 200 regels blijven, omdat een langer bestand meer context kost en de agent het minder betrouwbaar volgt. Codex stopt standaard met lezen zodra de AGENTS.md-inhoud 32 KiB bereikt.

Wat erin hoort:

• Commando's. Hoe je installeert, bouwt, draait en test, zo geschreven dat de agent ze kan uitvoeren zonder iets te vragen. "Draai composer test voor elke commit" werkt beter dan "test je wijzigingen".

• Afspraken die afwijken van de standaard. Naamgeving, mappenindeling, de ORM die je gebruikt, hoe migraties verlopen. De agent kent de taal al; hij kent jouw huisregels niet.

• Verboden terrein. De map met gegenereerde code, de productieconfiguratie, de factuurmodule die nog geen tests heeft en waar niemand aankomt zonder een mens erbij.

• Lessen. De fouten die de agent twee keer maakte. Daarover verder meer.

Wat er niet in hoort:

• Geheimen. Het bestand zit in de repository, wordt gelezen door elke collega en elke tool, en gaat bij elke sessie naar een modelleverancier. Op een website is het per definitie publiek, en de documentatie van Shopify waarschuwt zelf om geen contactgegevens in /agents.md te zetten.

• Alles wat de agent zelf uit de code kan afleiden. De /doctor-controle van Claude Code stelt net daarvoor snoeiwerk voor: mappenlijsten, lijsten met dependencies en architectuuroverzichten gaan eruit, de redenen en de afspraken blijven.

• Lange procedures. Een releasechecklist van twaalf stappen hoort in een apart bestand of in een agent skill die de agent laadt als hij ze nodig heeft, niet in het bestand waarmee elke sessie begint.

Ingevuld ziet een bestand voor een kleine Symfony-koppeling met een webshop er zo uit:

# Webshop sync

Symfony 7-app die elke nacht webshopbestellingen naar het ERP duwt.

## Commando's
- Installeren: composer install
- Tests: composer test (moet slagen voor elke commit)
- Draai bin/console app:sync:run nooit tegen .env.prod

## Regels
- Bedragen worden opgeslagen in centen als integers, nooit als floats
- Nieuwe ERP-velden gaan via src/Erp/Mapper.php en nergens anders
- Pas niets onder var/ of migrations/ met de hand aan

Veertien regels, en de agent weet hoe hij de tests draait, welke fout duur zou zijn en welke mappen zijn zaken niet zijn.

Instructiebestand tegenover system prompt

De twee zijn makkelijk te verwarren, want allebei zijn het tekst die het model leest voor het iets doet. Het verschil zit in wie ze schrijft en waar ze staan.

De system prompt schrijft wie het agentproduct bouwt. Anthropic schrijft die van Claude Code, OpenAI die van Codex, en bouw je zelf een agent op een API, dan schrijf je hem in je code. Hij zit in de toepassing en wie de agent gebruikt, krijgt hem nooit te zien.

Het instructiebestand schrijft wie de plek beheert waar de agent werkt: het team dat de repository beheert, de handelaar die de winkel runt. Het staat naast het werk, in versiebeheer of op een URL, en iedereen kan het openen. De documentatie van Claude Code is duidelijk over hoe het bij het model raakt: de inhoud wordt afgeleverd als een gebruikersbericht na de system prompt, niet als deel van de system prompt zelf. Het model leest het dus en probeert het te volgen, maar de instructies van het product zelf gaan voor, en wat jij rechtstreeks in de chat typt, gaat boven het bestand.

Daar volgen twee dingen uit. Het bestand is context, dus het verbruikt bij elke sessie tokens uit het context window. Daarom zegt elke leverancier: hou het kort. En het is richting, geen afdwinging. Mag iets nooit gebeuren, zoals een push naar de main branch, dan raadt Anthropic een toestemmingsregel of een hook aan die de client afdwingt, wat het model ook beslist. Het bestand zegt de agent wat jij graag wil; de instellingen bepalen wat hij kan.

Lessen terugschrijven in het bestand

Coding agents beginnen elke sessie met een leeg geheugen. Wat je gisteren uitlegde, is vandaag weg, tenzij het in het bestand staat. Zo wordt het instructiebestand de plek waar de ervaring van een team met de agent zich opstapelt.

De richtlijnen van Anthropic zeggen wanneer je een regel toevoegt: als de agent dezelfde fout een tweede keer maakt, als een code review iets opmerkt dat hij over deze codebase had moeten weten, of als je dezelfde correctie typt die je vorige sessie ook al typte. Every, de uitgever achter de plugin voor compound engineering, maakte er in december 2025 een loop van: plannen, werken, beoordelen, en dan compound, waarbij de engineer wat er geleerd is terugschrijft in prompts die in de codebase leven, zodat de volgende feature makkelijker te bouwen is dan de vorige.

In de praktijk is de gewoonte klein. De agent zet een float in een prijsveld; jij corrigeert; jij voegt "Bedragen worden opgeslagen in centen als integers" toe aan het bestand. Volgende week begint de sessie van een collega met die regel al geladen.

Het bestand vraagt evenveel snoeien als toevoegen. Anthropic waarschuwt dat de agent bij twee tegenstrijdige regels er willekeurig een kiest, en een regel over een module die niet meer bestaat, is pure kost. Lees het bestand elk kwartaal zoals je een onboardingdocument zou lezen, en schrap wat niet meer klopt.

Wat betekent dit voor een KMO?

Je hoeft geen code te schrijven om hier iets aan te hebben. Twee stappen volstaan voor de meeste bedrijven.

Vraag je softwareleverancier naar de AGENTS.md van de repository. Werken ze met coding agents, dan bestaat dat bestand of zou het moeten bestaan. Lees het. Het is de kortste eerlijke beschrijving van je project die je zal krijgen: wat het is, hoe het getest wordt, welke stukken fragiel zijn. Is het antwoord "dat hebben we niet", vraag dan hoe de agent weet welke tests hij moet draaien. Staat er "geen tests", dan heb je iets geleerd over de codebase waarvoor je betaald hebt. Het dient meteen ook als overdrachtsdocument: een nieuwe ontwikkelaar, mens of agent, vertrekt van dezelfde pagina.

Zet een llms.txt op je website. Dat zijn twintig regels Markdown: je bedrijfsnaam, één alinea over wat je doet, links naar de pagina's die echte vragen beantwoorden (producten, prijzen, openingsuren, support, de pagina's die uitleggen wat je niet doet). Wie je site beheert, zet het er op een namiddag op. Draai je een Shopify-winkel, dan heb je er al een; kijk na wat erin staat en haal eruit wat je niet op een visitekaartje zou zetten.

Waar moet je op letten bij agent-instructiebestanden

Niemand heeft bewezen dat llms.txt gelezen wordt. Het Search-team van Google zegt dat Google Search het niet gebruikt. In januari 2026 antwoordde John Mueller op Bluesky, op de vraag of Google er zelf een publiceren voor zijn docs een goedkeuring was, met een droog "no", en in juni 2026 noemde hij het bestand "purely speculative for now", met de opmerking dat geen enkel AI-systeem het gebruikt. De documentatie van Google over AI-functies zegt dat je geen nieuwe machineleesbare bestanden nodig hebt om in AI Overviews of AI Mode te verschijnen. Dat Anthropic en anderen een llms.txt publiceren voor hun eigen documentatie, zegt niets over of hun agents de jouwe ophalen. Zie het bestand als goedkoop en onschadelijk, niet als een hefboom voor je ranking, en wees op je hoede voor wie het zo verkoopt.

Het bestand is een ingang voor injectie. Een repositorybestand leest de agent als instructies, dus een kwaadwillige of slordige pull request die het aanpast, verandert wat elke volgende sessie doet. Review wijzigingen aan AGENTS.md zoals je wijzigingen aan een deployscript reviewt. Omgekeerd geldt hetzelfde voor sitebestanden: een agent die de llms.txt van een vreemde ophaalt, leest tekst die die vreemde schreef, en een goed gebouwde agent behandelt die als onbetrouwbare inhoud. Dat is één verdedigingslijn tegen prompt injection.

Verouderde instructies kosten meer dan geen instructies. Een regel die verwijst naar een map die verhuisd is, of een commando dat niet meer bestaat, stuurt de agent vol vertrouwen de verkeerde kant op. Het bestand heeft een eigenaar nodig.

Te veel bestanden, te veel tools. Een monorepo met een dozijn geneste AGENTS.md-bestanden plus een CLAUDE.md plus Cursor-regels levert een context op die de agent niet kan volgen. Kies één bestand als bron van de waarheid en laat de andere het importeren; de documentatie van Claude Code toont daarvoor een import van één regel, @AGENTS.md.