Codex AGENTS.md: projectafspraken die je kunt controleren

AGENTS.md is een tekstbestand met projectinstructies voor Codex. Je legt er bijvoorbeeld vast hoe je tests draait, welke bestaande structuur gevolgd moet worden en wanneer een wijziging eerst overleg vraagt. Daarmee maak je afspraken vindbaar voor een nieuwe ontwikkelsessie.

Ik zou het bestand behandelen als een korte werkafspraak die een collega ook kan gebruiken. Geen verzameling van elk gesprek dat ooit over het project is gevoerd. Hieronder staat een eigen voorbeeld, met de officiële laadregels gecontroleerd op 27 oktober 2026.

Begin met informatie die bepaalt hoe iemand verantwoord in dit project werkt. Waar staan de onderdelen? Welk commando controleert een wijziging? Welke bestanden worden automatisch gegenereerd? Welke handeling vereist een aparte beslissing? Zulke afspraken voorkomen dat de agent bij iedere taak opnieuw moet gokken.

Gebruik concrete taal. 'Schrijf goede tests' laat veel open. 'Controleer dat een bestaande reservering zijn tijd behoudt wanneer alleen de naam wordt aangepast' beschrijft toetsbaar gedrag. Niet elke test hoort letterlijk in AGENTS.md; een verwijzing naar een actuele testinstructie kan voldoende zijn.

Een lang verslag van vorige sessies maakt de kern juist minder zichtbaar. Bewaar tijdelijke voortgang op de daarvoor afgesproken plek. Het projectbestand moet bruikbaar blijven voor iemand die de voorgeschiedenis niet kent.

De officiële documentatie beschrijft een keten van globale instructies naar projectinstructies tot de huidige werkmap. Per map heeft een niet-leeg AGENTS.override.md voorrang op AGENTS.md. Instructies dichter bij de werkmap krijgen later een plek in de gecombineerde instructies.

De ontdekking gebeurt bij de start van de run. De standaardlimiet voor de gecombineerde projectdocumentatie is 32 KiB. Controleer daarom in een nieuwe sessie welke bestanden zijn geladen, vooral wanneer je instructies hebt gewijzigd of vanuit een submap start.

Die laadvolgorde heeft praktische gevolgen. Een afspraak voor de hele app staat op projectniveau. Een aanvullende afspraak voor een specifieke service kan dichter bij die service staan. Maak daarbij duidelijk wat de aanvulling betekent; tegenstrijdige teksten laten ook voor mensen ruimte voor misverstanden.

Dit zelfbedachte voorbeeld gaat over een kleine roosterapp. De testregel is bewust een opdracht om de bestaande projectinstructie te volgen, geen aanname over de testsoftware van jouw project.

Het bestand zegt hoe je in het project werkt en waar je actuele commando's vindt. Het belooft niet dat een controle slaagt. Als de README geen bruikbaar testpad bevat, is dat een open vraag om te herstellen, geen ruimte om een groen resultaat te verzinnen.

Begin na het toevoegen een nieuwe Codex-sessie vanuit de bedoelde projectmap. Vraag: 'Noem welke instructiebestanden voor deze map gelden en vat de testafspraken samen. Verander niets.' Vergelijk het antwoord met de werkelijke bestanden.

Start daarna vanuit een relevante submap en herhaal de vraag. Zo ontdek je of de extra serviceafspraak op de bedoelde plaats staat. Een samenvatting van de regels bewijst alleen dat ze zijn herkend; de volgende echte taak moet nog laten zien dat het werk conform die afspraken is uitgevoerd.

Neem bijvoorbeeld een wijziging in de reserveringsduur. Vraag na afloop waar het gedrag is aangepast en welke test het afdekt. Als alleen een knoptekst is veranderd terwijl de validatie op de server gelijk blijft, moet dat in de controle zichtbaar worden.

AGENTS.md bevat doorlopende projectafspraken. Een skill beschrijft een herbruikbare procedure die bij een bepaalde taak past. Mijn voorkeur: zet de basisafspraak compact in het projectbestand en werk een lange werkwijze op een passende plek uit.

De technische veiligheidsinstellingen bepalen toegang en goedkeuringen. 'Lees geen geheimen' in een tekstbestand is geen vervanging voor het beperken van toegang tot die bestanden. Controleer bij gevoelige projecten dus ook de feitelijke instellingen.

Onze uitleg over guardrails helpt om die twee soorten afspraken uit elkaar te houden. Een nuttige vraag is steeds: wordt deze regel alleen verteld, of wordt hij ook technisch afgedwongen?

Wijs een eigenaar aan en werk de instructie bij als de echte werkwijze verandert. Verwijst het bestand naar een verdwenen script, dan moet de eerstvolgende wijziging ook die verwijzing herstellen. Laat een nieuwe afspraak eerst door een collega nalopen: begrijpt die hetzelfde als jij?

Verwijder regels die niets toevoegen en geef specifieke afspraken een duidelijke plek. Een bestand met vijf juiste regels is bruikbaarder dan tientallen regels die niemand nog controleert. Lees voor heldere formulering ook de gids over prompt engineering. Wil je dit oefenen binnen een eigen appproject, bekijk de Vibe Coding Training.