STACK versus AGENTS.md: waar instructies ophouden en harde controles beginnen

Een instructiebestand is een verzoek. Een harde controle is een weigering. Dat verschil bepaalt of de regel die je voor je AI-codeeragent schreef, standhoudt op een slechte dag.

AGENTS.md is een gewoon Markdown-bestand in een coderepository dat AI-codeeragents vertelt hoe het project werkt: hoe je het installeert, hoe je de tests draait, welke conventies gelden. Agents lezen het als context. Het stuurt ze dus wel, maar het kan ze niet tegenhouden. STACK is een kaart in vijf lagen van wat een repository nodig heeft zodra er agents in werken, en AGENTS.md is één bestand in een van die lagen. Regels die altijd moeten gelden (nooit rechtstreeks naar de hoofdbranch pushen, nooit aan productiedata komen) horen in harde controles: rechteninstellingen, hooks, sandboxes, branchbeveiliging en automatische checks.

Eerst een paar begrippen. Een codeeragent is een AI-programma dat zelfstandig, in meerdere stappen, code leest en aanpast, zoals Codex van OpenAI, Jules van Google of Claude Code. Een repository (repo) is de map met de code van een project en de geschiedenis ervan, bijgehouden met versiebeheer. Een harde controle is alles wat een actie blokkeert of afdwingt, wat de agent ook besluit.

Wat is AGENTS.md?

De officiële site noemt het “a simple, open format for guiding coding agents, used by over 60k open-source projects”: een eenvoudig, open formaat om codeeragents te sturen, in gebruik bij meer dan 60.000 opensourceprojecten. De site spreekt van een “README for agents”, een vaste plek voor de buildstappen, tests en conventies die een agent nodig heeft (agents.md).

Drie details van die site doen ertoe voor de rest van dit stuk:

• Geen schema. “AGENTS.md is just standard Markdown.” Er zijn geen verplichte velden.
• Het dichtstbijzijnde bestand wint, en de chat wint van alles. Een grote repo kan in elke map een AGENTS.md hebben. Spreken instructies elkaar tegen, dan geldt: “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.” Het bestand dat het dichtst bij de gewijzigde code staat, wint. Een expliciete chatprompt gaat boven alles.
• Naar beste vermogen. Over testcommando’s in het bestand zegt de site: “The agent will attempt to execute relevant programmatic checks and fix failures before finishing the task.” De agent zal het dus proberen. Proberen is hier het eerlijke woord.

Het formaat ontstond bij OpenAI Codex, Amp, Jules van Google, Cursor en Factory. Op 9 december 2025 kondigde de Linux Foundation de Agentic AI Foundation aan, met AGENTS.md van OpenAI als een van de eerste projecten, naast het Model Context Protocol van Anthropic en goose van Block (Linux Foundation). Volgens de AGENTS.md-site beheert die stichting het formaat nu.

Wat kan AGENTS.md niet?

Het kan niets afdwingen, en de makers van de tools zeggen dat zelf, met zoveel woorden.

Claude Code leest CLAUDE.md-bestanden en kan ook AGENTS.md lezen. De documentatie van Anthropic zegt dat die instructiebestanden worden behandeld “as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.” Ze zijn dus context, geen afgedwongen configuratie; wie een actie wil blokkeren, gebruikt een hook. Een hook is een klein script dat de tool op een vast moment uitvoert, hier vlak voor een toolaanroep, en dat die aanroep kan tegenhouden. Op dezelfde pagina staat ook: “Settings rules are enforced by the client regardless of what Claude decides to do.” Instellingen dwingt de software wél af (Claude Code-documentatie).

De documentatie van Codex van OpenAI beschrijft de harde controles als twee lagen. Een sandbox bepaalt “What Codex can do technically (for example, where it can write and whether it can reach the network)”: wat Codex technisch kan, zoals waar Codex mag schrijven en of het netwerk bereikbaar is. Een goedkeuringsbeleid bepaalt wanneer Codex het jou eerst moet vragen (Codex-documentatie). Geen van beide lagen is een instructiebestand.

En dan is er de voorrangsregel. Een chatprompt gaat bewust boven AGENTS.md. Een regel die één haastig bericht kan opheffen, is een voorkeur, geen garantie.

Een echt voorbeeld: de codefreeze die alleen uit woorden bestond

In juli 2025 meldde Jason Lemkin, oprichter van de SaaS-community SaaStr, dat de AI-agent van de online programmeerdienst Replit een productiedatabase had gewist, terwijl hij de agent had opgedragen zonder toestemming geen code te veranderen (The Register). Op 20 juli schreef hij: “There is no way to enforce a code freeze in vibe coding apps like Replit. There just isn’t.” Een codefreeze afdwingen kon gewoon niet.

Kijk wat de oplossing was. Amjad Masad, de CEO van Replit, zei dat het bedrijf “started rolling out automatic DB dev/prod separation to prevent this categorically” (The Register). Geen strengere instructie dus, maar een structurele maatregel: aparte databases voor ontwikkeling en productie, zodat werk in uitvoering niet meer op klantdata in productie draait. Volgens Replit zou dat eerst voor nieuwe apps beschikbaar komen, als bèta.

De berichtgeving vermeldt niet waar de instructie voor de codefreeze stond, en voor de les maakt het niet uit. Tekst vraagt. Structuur weigert.

Waar hoort AGENTS.md in STACK?

STACK is een framework om een repository zo in te richten dat mensen en AI-agents hem kunnen delen zonder dat hij verloedert. Het onderscheidt vijf lagen, elk met een eigen taak:

1. Structure. De indeling, de toegangspunten en de grenzen waar een agent in zijn eerste minuut de weg in vindt.
2. Toolchain. De shells, commando’s en opdrachtregeltools die een agent mag draaien, opgeschreven in plaats van onthouden.
3. Agent configuration. AGENTS.md, CLAUDE.md, regels, skills en rolbeschrijvingen voor subagents, onder versiebeheer als vaste context.
4. Connection. MCP-servers (MCP is de standaard waarmee AI-tools met externe systemen praten), toolcontracten, hooks en vangrails, met zo weinig rechten als elke klus nodig heeft en een bekend faalscenario.
5. Knowledge and quality. Geheugen, contextbudgetten, evaluaties en continuous integration (CI: checks die bij elke wijziging automatisch draaien), zodat een modelupgrade de lat niet stilletjes verlaagt.

STACK komt uit De agentische codebase, een boek van de auteur van deze site, dat nu verkrijgbaar is. Je hebt het boek niet nodig om ermee te werken. De frameworkpagina zet de lagen op een rij, en Wat is STACK? loopt ze langs aan de hand van een realistische repo.

“STACK versus AGENTS.md” is dus geen keuze. AGENTS.md is het hoofdbestand van laag 3. Het boek noemt het centrale instructiebestand de grondwet van de repo, en vat de regel voor die laag samen in één zin: “De grondwet stuurt; een hook dwingt af.” Het waarom zet je in het instructiebestand. Het moet zet je in een harde controle in laag 2, 4 of 5.

Welke regels horen in AGENTS.md, en welke vragen om een harde controle?

Regel	In AGENTS.md zetten?	Harde controle die hem afdwingt	STACK-laag van die controle
Draai de tests voordat je een wijziging af noemt	Ja: het exacte commando	Een verplichte CI-check vóór de merge	Knowledge and quality
Nooit rechtstreeks naar main pushen	Ja, met de reden	Branchbeveiliging, plus een hook die de push blokkeert	Connection
Nooit .env of andere geheime bestanden lezen	Ja	Een weigerregel in de rechteninstellingen van de agent; geheimen buiten de repo	Connection
Nooit aan productiedata komen	Ja	Geen productiewachtwoorden of -sleutels in de omgeving van de agent; aparte databases	Connection
Vraag eerst voordat je onbekende commando’s draait	Ja	Het goedkeuringsbeleid van de tool	Connection
Gebruik pnpm, niet npm	Ja	Een vastgelegde toolchain; eventueel een hook	Toolchain
Enkele aanhalingstekens, geen puntkomma’s	Ja	Een formatter of linter in CI	Knowledge and quality
Waar welk deel van de code staat	Ja: een korte kaart	Niet nodig	Structure

De gedachte achter de tabel past op één regel: kost één overtreding meer dan een excuus, dan hoort er een harde controle bij. Laat de zin toch in AGENTS.md staan, zodat de agent begrijpt waarom hij wordt tegengehouden.

Op GitHub bijvoorbeeld bepalen regels voor branchbeveiliging “whether collaborators can delete or force push to the branch and set requirements for any pushes to the branch, such as passing status checks or a linear commit history”: of iemand een branch mag verwijderen of force-pushen, en aan welke eisen een push moet voldoen (GitHub Docs). Zolang het account van de agent deze instelling niet kan wijzigen, praat geen prompt zich erlangs.

Hoe loop je een AGENTS.md in 15 minuten na?

1. Zoek alle instructiebestanden (3 minuten). Zoek naar AGENTS.md in elke map, en naar CLAUDE.md, .cursor/rules en .github/copilot-instructions.md. Spreken twee bestanden elkaar tegen, kies dan één bron van waarheid en laat de andere ernaar verwijzen. De documentatie van Claude Code laat bijvoorbeeld zien hoe je AGENTS.md importeert vanuit CLAUDE.md.
2. Markeer elk hard woord (3 minuten). Markeer elke regel met nooit, altijd, moet of mag niet.
3. Zet de harde controle ernaast (5 minuten). Noteer bij elke gemarkeerde regel welke harde controle hem afdwingt, of schrijf “geen”.
4. Sorteer de regels met “geen” (2 minuten). Kost één overtreding meer dan een excuus? Dan gaat de regel op het lijstje voor deze week: een hook, een weigerregel, een instelling voor branchbeveiliging of een CI-check.
5. Bekijk de lengte (2 minuten). De documentatie van Claude Code waarschuwt dat langere bestanden “consume more context and reduce adherence”: ze kosten meer context en worden slechter opgevolgd. Verplaats situatiegebonden details naar bestanden die alleen worden geladen als ze nodig zijn.

Wat je bij die doorlichting naar een harde controle verplaatst, is meteen een kandidaat voor je override-doctrine: het korte lijstje dingen die een agent nooit mag doen.

Probeer het vandaag

Open de AGENTS.md of CLAUDE.md van je repository. Neem de eerste regel met “nooit” en pas stap 3 en 4 erop toe. Staat er in de kolom “geen” en beschermt de regel geld, klantdata of productie? Zet dan vandaag nog één harde controle op.

Het bestand blijft. Het is alleen niet langer het enige wat tussen de agent en de fout staat.

Citeer deze pagina:STACK versus AGENTS.md: waar instructies ophouden en harde controles beginnen.Len P. van der Hof. https://lenvanderhof.com/nl/blog/stack-versus-agents-md/ · Gepubliceerd 1 oktober 2026.