Wat is Agents.md en hoe gebruik je het?
Auteur: Redactie Domeny.ForSale Gepubliceerd
Kort gezegd: AGENTS.md is een tekstbestand met instructies voor AI-agenten die aan een project werken, meestal aan code. Het beschrijft onder meer hoe je tests uitvoert, hoe het project is georganiseerd en welke regels gelden voor wijzigingen. Het bestand voert zelf niets uit: het effect hangt af van de vraag of de gebruikte tool het leest en hoe die de aanwijzingen interpreteert.
Waarvoor dient het bestand AGENTS.md?
Een AI-agent is een tool die niet alleen vragen beantwoordt, maar ook taken kan uitvoeren, zoals bestanden bekijken, code bewerken en opdrachten uitvoeren. Daarvoor heeft de agent context over het specifieke project nodig. Zonder die context kan hij afhankelijkheden op de verkeerde manier installeren of bestanden wijzigen die het team niet handmatig bewerkt.
Met AGENTS.md kun je die context vastleggen in de repository: de plek waar de code en de wijzigingsgeschiedenis worden bewaard. Het bestand gebruikt Markdown, een eenvoudig tekstformaat met ondersteuning voor koppen, lijsten en codeblokken. Je kunt het in een gewone teksteditor bewerken en samen met de overige projectwijzigingen beoordelen.
Het is een conventie om instructies door te geven, geen programma, AI-model of mechanisme om toegangsrechten toe te kennen. De instructie ‘wijzig de productieconfiguratie niet’ geeft de agent een aanwijzing, maar blokkeert technisch gezien niet de toegang tot die configuratie.
AGENTS.md en README: verschillende documentatiedoelen
README.md introduceert het project doorgaans voor mensen: het legt het doel, de installatie en het basisgebruik uit. AGENTS.md beschrijft vooral hoe de agent in de betreffende repository moet werken. De twee bestanden kunnen elkaar aanvullen in plaats van dezelfde documentatie te herhalen.
De README van een bibliotheek kan bijvoorbeeld laten zien hoe je die in je eigen applicatie gebruikt. De instructies voor de agent kunnen daarentegen bepalen dat na een wijziging aan de publieke interface ook de voorbeelden moeten worden bijgewerkt en een specifieke reeks tests moet worden uitgevoerd.
Verwar AGENTS.md ook niet met llms.txt, een bestand dat is voorgesteld om taalmodellen informatie over de inhoud van een website te bieden. AGENTS.md gaat vooral over werken aan een project, niet over het presenteren van website-inhoud. De aanwezigheid van het bestand zegt niets over de zichtbaarheid van de website in zoekmachines of AI-diensten.
Waar plaats je het bestand en leest elke tool het?
De gebruikelijke plek is de hoofdmap van de repository. Gebruik bij het aanmaken de naam AGENTS.md, met hoofdletters: op systemen die onderscheid maken tussen hoofdletters en kleine letters kan Agents.md een ander bestand zijn. Ga er niet van uit dat de tool elke schrijfwijze van de naam herkent.
In grotere projecten staan soms extra AGENTS.md-bestanden in submappen, bijvoorbeeld afzonderlijk voor de gebruikersinterface en het servergedeelte. Zo kun je regels voor verschillende technologieën scheiden. Waar de instructies gelden en hoe tegenstrijdigheden worden opgelost, hangt echter af van de tool. Ga daarom niet uit van één vaste hiërarchie voor alle agenten.
Controleer vóór de invoering in de officiële documentatie van de gebruikte agent:
- of de agent
AGENTS.mdondersteunt en of daarvoor extra configuratie nodig is; - in welke mappen de agent naar instructies zoekt;
- of de agent bestanden in submappen leest;
- hoe de agent deze combineert met de opdracht van de gebruiker en andere instructies.
Alleen het toevoegen van het bestand aan de repository betekent niet dat elke AI-functie in de editor het gaat gebruiken.
Wat zet je in de instructies voor de agent?
Het nuttigst is informatie die giswerk voorkomt: concrete opdrachten, de locatie van belangrijke bestanden en de grenzen van de gevraagde wijziging. Een algemene aanwijzing als ‘schrijf goede code’ vertelt de agent niet hoe hij het resultaat moet controleren.
Een voorbeeldbestand voor een JavaScript-project dat npm gebruikt, kan er zo uitzien. De opdrachten zijn alleen zinvol als ze aansluiten op de configuratie van de betreffende repository:
## Werken aan het project
## Uitvoeren en controleren
- Installeer afhankelijkheden met de opdracht `npm ci`.
- Voer tests uit met de opdracht `npm test`.
- Controleer de code op naleving van de regels met de opdracht `npm run lint`.
- Als je een controle niet kunt uitvoeren, vermeld dan de reden.
## Bestandsindeling
- De applicatiecode staat in `src/`.
- Bewerk niet handmatig de map `generated/`.
## Reikwijdte van wijzigingen
- Voeg geen afhankelijkheden toe zonder bevestiging van de gebruiker.
- Voeg bij het oplossen van een bug een test toe die de bug reproduceert.
- Combineer de bugfix niet met het opschonen van code die er niets mee te maken heeft.
Vermeld bij een project met meerdere applicaties voor elke opdracht vanuit welke map die moet worden uitgevoerd. Als de tests een aanvullende dienst vereisen, beschrijf dan die vereiste en hoe je de omgeving veilig voorbereidt. Zet geen wachtwoorden, tokens of andere geheimen in de instructies.
Hoe controleer je de werking en houd je het bestand actueel?
Een kleine taak is een goede proef, bijvoorbeeld het verbeteren van de validatie van één formulierveld. Kijk of de agent de juiste opdrachten gebruikt, automatisch gegenereerde bestanden ongemoeid laat en meldt welke tests niet zijn uitgevoerd. Als de tool laat zien welke instructies zijn ingelezen, controleer dan ook die informatie.
Als de agent een fout maakt, ga dan eerst na of hij het bestand heeft gelezen. Meer verboden toevoegen helpt niet als het probleem ontbrekende ondersteuning of een verkeerde bestandslocatie is. Als de instructie wel is gelezen, vervang een onduidelijke formulering dan door een concrete handeling of voorwaarde.
Behandel AGENTS.md als onderdeel van de documentatie die je onderhoudt: werk het bij wanneer opdrachten, de mappenstructuur of het testproces veranderen. Dwing toegangsbeperkingen af met toegangsrechten en de configuratie van de omgeving, niet alleen met zinnen in een bestand. Leg om te beginnen werkende controleopdrachten en de belangrijkste beperkingen vast en toets die vervolgens met één kleine taak.
Zie ook: Wat is GitHub?
Lees ook
