--- title: "STACK versus AGENTS.md: instructies of harde controles | Len P. van der Hof" description: "STACK versus AGENTS.md: AGENTS.md vertelt codeeragents hoe je repo werkt, maar dwingt niets af. Welke regels erin horen en welke om een harde controle vragen." image: "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.wide.webp" --- [AI-systemen](https://lenvanderhof.com/nl/blog/categorie/ai-systemen/) Onderzoeksartikel # STACK versus AGENTS.md: waar instructies ophouden en harde controles beginnen Een instructiebestand is een verzoek. Een harde controle is een weigering. Len P. van der HofGepubliceerd 1 oktober 20268 min. leestijd De geschilderde lijn vroeg het. De paal weigerde. Direct antwoord AGENTS.md is een gewoon Markdown-bestand in een coderepository dat AI-codeeragents vertelt hoe het project werkt: installatie, tests, conventies. Het is een open formaat onder beheer van de Agentic AI Foundation. Agents lezen het als context, dus het stuurt wel, maar dwingt niets af. STACK, uit De agentische codebase, is een kaart in vijf lagen van wat een repository nodig heeft zodra er agents in werken; AGENTS.md hoort in de laag Agent configuration. Regels die altijd moeten gelden, horen in harde controles: rechteninstellingen, hooks, sandboxes, branchbeveiliging en automatische checks. ## Belangrijkste inzichten - AGENTS.md is een README voor codeeragents: gewone Markdown, geen verplichte velden, volgens de eigen site gebruikt door meer dan 60.000 opensourceprojecten. - Het is context, geen harde controle. Volgens de eigen regels van het formaat gaat een expliciete chatprompt erboven. - Kost één overtreding meer dan een excuus, dwing de regel dan af met een harde controle en laat de reden in AGENTS.md staan. - In STACK hoort AGENTS.md bij Agent configuration. Afdwingen gebeurt in Toolchain, Connection en Knowledge and quality. 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](https://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](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-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](https://code.claude.com/docs/en/memory)). 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](https://learn.chatgpt.com/docs/agent-approvals-security)). 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](https://www.theregister.com/2025/07/21/replit_saastr_vibe_coding_incident/)). 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](https://www.theregister.com/2025/07/22/replit_saastr_response/)). 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](https://lenvanderhof.com/nl/begrippen/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](https://lenvanderhof.com/boeken/the-agentic-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](https://lenvanderhof.com/nl/frameworks/stack/) zet de lagen op een rij, en [Wat is STACK?](https://lenvanderhof.com/nl/blog/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? RegelIn AGENTS.md zetten?Harde controle die hem afdwingtSTACK-laag van die controleDraai de tests voordat je een wijziging af noemtJa: het exacte commandoEen verplichte CI-check vóór de mergeKnowledge and qualityNooit rechtstreeks naar main pushenJa, met de redenBranchbeveiliging, plus een hook die de push blokkeertConnectionNooit .env of andere geheime bestanden lezenJaEen weigerregel in de rechteninstellingen van de agent; geheimen buiten de repoConnectionNooit aan productiedata komenJaGeen productiewachtwoorden of -sleutels in de omgeving van de agent; aparte databasesConnectionVraag eerst voordat je onbekende commando’s draaitJaHet goedkeuringsbeleid van de toolConnectionGebruik pnpm, niet npmJaEen vastgelegde toolchain; eventueel een hookToolchainEnkele aanhalingstekens, geen puntkomma’sJaEen formatter of linter in CIKnowledge and qualityWaar welk deel van de code staatJa: een korte kaartNiet nodigStructure 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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)). 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](https://lenvanderhof.com/nl/blog/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/](https://lenvanderhof.com/nl/blog/stack-versus-agents-md/) · Gepubliceerd 1 oktober 2026. ## Begrippen - [STACK](https://lenvanderhof.com/nl/begrippen/stack/) ## Bronnen 1. [AGENTS.md](https://agents.md/) · AGENTS.md, a Series of LF Projects 2. [Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) · The Linux Foundation 3. [How Claude remembers your project](https://code.claude.com/docs/en/memory) · Anthropic (documentatie van Claude Code) 4. [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide) · Anthropic (documentatie van Claude Code) 5. [Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security) · OpenAI (documentatie van Codex) 6. [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) · GitHub Docs 7. [Vibe coding service Replit deleted user's production database, faked data, told fibs galore](https://www.theregister.com/2025/07/21/replit_saastr_vibe_coding_incident/) · The Register (Simon Sharwood) 8. [Replit makes vibe-y promise to stop its AI agents making vibe coding disasters](https://www.theregister.com/2025/07/22/replit_saastr_response/) · The Register 9. [STACK (framework)](https://lenvanderhof.com/nl/frameworks/stack/) 10. [De agentische codebase](https://lenvanderhof.com/boeken/the-agentic-codebase/) 11. [Wat is STACK? Vijf lagen, geen diagram van een leverancier](https://lenvanderhof.com/nl/blog/wat-is-stack/) 12. [Wat een agent nooit mag doen](https://lenvanderhof.com/nl/blog/override-doctrine/) ## Verder lezen - [Wat is STACK? Vijf lagen, geen diagram van een leverancier](https://lenvanderhof.com/nl/blog/wat-is-stack/) - [STACK: versioneer het agent-OS zoals je de app versioneert](https://lenvanderhof.com/nl/blog/stack-versioneer-het-agent-os/) - [De agentische codebase](https://lenvanderhof.com/boeken/the-agentic-codebase/) Over de auteur ## [Len P. van der Hof](https://lenvanderhof.com/nl/auteurs/len-p-van-der-hof/) Ondernemer, AI-innovator en venture builder Len P. van der Hof bouwt praktische AI-systemen, digitale ventures en evidence-informed hulpmiddelen voor founders. ```json { "@context": "https://schema.org", "@graph": [ { "@type": "Person", "@id": "https://lenvanderhof.com/#person", "name": "Len P. van der Hof", "alternateName": [ "Len van der Hof", "L.P. van der Hof", "Leendert Pieter van der Hof" ], "honorificSuffix": "MSc", "url": "https://lenvanderhof.com/", "image": [ "https://lenvanderhof.com/photos/len-portrait-1.jpg", "https://lenvanderhof.com/photos/len-portrait-2.jpg", "https://lenvanderhof.com/photos/len-portrait-3.jpg", "https://lenvanderhof.com/photos/len-portrait-4.jpg", "https://lenvanderhof.com/photos/len-speaking.jpg", "https://lenvanderhof.com/photos/len-hero.jpg" ], "jobTitle": "Ondernemer, AI-innovator en venture builder", "description": "Len P. van der Hof, MSc, is een Nederlandse ondernemer en AI-innovator in Zwijndrecht. Hij bouwt ReasonKit, MindSesh, Undominated.ai, boeken onder zijn eigen naam, het fictie-imprint LPH98.lifestyle en technologieventures via LPH98.ventures. Elf titels in Systems for the Strategic Self zijn nu verkrijgbaar, in het Engels en het Nederlands.", "address": { "@type": "PostalAddress", "addressLocality": "Zwijndrecht", "addressCountry": "NL" }, "alumniOf": { "@type": "CollegeOrUniversity", "name": "Rotterdam School of Management, Erasmus University" }, "knowsAbout": [ "Artificial intelligence", "AI agents", "Agentic AI systems", "LLM routing", "SEO", "Generative engine optimization", "Answer engine optimization", "Venture building", "Founder performance", "Founder psychology", "Evidence-based decision-making" ], "sameAs": [ "https://www.linkedin.com/in/lenvanderhof/", "https://x.com/LenvanderHof", "https://www.youtube.com/channel/UCTG20buKqYYbitqqf7l3zJA", "https://www.instagram.com/Lenvanderhof/", "https://www.threads.com/@lenvanderhof", "https://github.com/Lenvanderhof", "https://huggingface.co/LPH98", "https://www.npmjs.com/~lenvanderhof", "https://www.goodreads.com/author/show/70983905.Len_P_van_der_Hof", "https://www.amazon.com/author/lenvanderhof", "https://www.bol.com/nl/nl/b/len-p-van-der-hof-msc/609879394/", "https://bsky.app/profile/lenvanderhof.com", "https://mastodon.social/@Lenvanderhof", "https://crates.io/users/Lenvanderhof", "https://cursor.com/@Lenvanderhof", "https://medium.com/@Lenvanderhof", "https://gitlab.com/Lenvanderhof", "https://hub.docker.com/u/lenvanderhof/", "https://dev.to/lenvanderhof", "https://www.facebook.com/Lenvanderhof", "https://soundcloud.com/Lenvanderhof" ], "affiliation": [ { "@id": "https://lenvanderhof.com/#publisher" }, { "@id": "https://lenvanderhof.com/#mindsesh" }, { "@id": "https://lenvanderhof.com/#lifestyle" } ] }, { "@type": "WebSite", "@id": "https://lenvanderhof.com/#website", "url": "https://lenvanderhof.com/", "name": "Len P. van der Hof", "description": "Len P. van der Hof, MSc, is een Nederlandse ondernemer en AI-innovator in Zwijndrecht. Hij bouwt ReasonKit, MindSesh, Undominated.ai, boeken onder zijn eigen naam, het fictie-imprint LPH98.lifestyle en technologieventures via LPH98.ventures. Elf titels in Systems for the Strategic Self zijn nu verkrijgbaar, in het Engels en het Nederlands.", "inLanguage": [ "en", "nl" ], "publisher": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "Organization", "@id": "https://lenvanderhof.com/#publisher", "name": "LPH98.ventures", "url": "https://lph98.ventures", "founder": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "Organization", "@id": "https://lenvanderhof.com/#mindsesh", "name": "MindSesh", "url": "https://mindsesh.net", "founder": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "SoftwareApplication", "@id": "https://lenvanderhof.com/#reasonkit", "name": "ReasonKit", "url": "https://reasonkit.sh", "creator": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "SoftwareApplication", "@id": "https://lenvanderhof.com/#undominated", "name": "Undominated.ai", "url": "https://undominated.ai", "creator": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "Organization", "@id": "https://lenvanderhof.com/#lifestyle", "name": "LPH98.lifestyle", "url": "https://lph98.lifestyle", "founder": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "ImageObject", "@id": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/#primaryimage", "url": "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.wide.webp", "contentUrl": "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.wide.webp", "representativeOfPage": true }, { "@type": "BreadcrumbList", "@id": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/#breadcrumb", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://lenvanderhof.com/nl/" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://lenvanderhof.com/nl/blog/" }, { "@type": "ListItem", "position": 3, "name": "AI-systemen", "item": "https://lenvanderhof.com/nl/blog/categorie/ai-systemen/" }, { "@type": "ListItem", "position": 4, "name": "STACK versus AGENTS.md: waar instructies ophouden en harde controles beginnen", "item": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/" } ] }, { "@type": "WebPage", "@id": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/#webpage", "url": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/", "name": "STACK versus AGENTS.md: waar instructies ophouden en harde controles beginnen", "description": "STACK versus AGENTS.md: AGENTS.md vertelt codeeragents hoe je repo werkt, maar dwingt niets af. Welke regels erin horen en welke om een harde controle vragen.", "isPartOf": { "@id": "https://lenvanderhof.com/#website" }, "primaryImageOfPage": { "@id": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/#primaryimage" }, "breadcrumb": { "@id": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/#breadcrumb" }, "inLanguage": "nl-NL" }, { "@type": "BlogPosting", "@id": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/#article", "mainEntityOfPage": { "@id": "https://lenvanderhof.com/nl/blog/stack-versus-agents-md/#webpage" }, "headline": "STACK versus AGENTS.md: waar instructies ophouden en harde controles beginnen", "description": "STACK versus AGENTS.md: AGENTS.md vertelt codeeragents hoe je repo werkt, maar dwingt niets af. Welke regels erin horen en welke om een harde controle vragen.", "datePublished": "2026-10-01T19:05:00.000Z", "author": { "@id": "https://lenvanderhof.com/#person" }, "publisher": { "@id": "https://lenvanderhof.com/#person" }, "image": [ "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.square.webp", "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.landscape.webp", "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.wide.webp" ], "articleSection": "AI-systemen", "inLanguage": "nl-NL" } ] } ```