784 manieren om ‘niet doen' te zeggen: wat de grootste repo's in hun AGENTS.md zetten (2026)
By Surya Pratap
22 augustus 2026
12 min leestijd
AI en technologie
22 augustus 2026
12 min leestijd
Het bestand dat je bij elke sessie betaaltHover to exploreIemand op r/AI_Agents deed het werk dat niemand anders had gedaan: de AGENTS.md van de 100 GitHub-repo's met de meeste sterren die er een hebben gelezen — zo'n 27 % van de top 1.000, volgens die telling — en geteld wat erin staat.
De structurele bevinding was geen verrassing. Architectuur en repo-indeling, hoe je test, buildcommando's, do's en don'ts, PR-etiquette, codestijl. De meest voorkomende kopjes: testen, commando's, projectoverzicht, architectuur. Zoals verwacht.
Het interessante was de toon. Ongeveer 90 % van die bestanden is geschreven in moet/altijd/nooit. In het hele corpus staan 784 expliciete ‘niet doen'-bullets, en de meeste zijn opvallend specifiek.
De mooiste vondst:
‘Beweer niet dat een onderbroken of verlopen test is geslaagd.'
Niemand schrijft die zin in het abstracte. Je schrijft die zin omdat een agent het deed.
Dit is de herkadering die je moet meenemen, en ze verandert hoe je het bestand schrijft.
Een README schrijf je naar buiten toe: het legt een project uit aan iemand die het nooit heeft gezien. Een AGENTS.md die zo geschreven is, levert een keurig projectoverzicht op waar niemand iets aan heeft, want de agent kan je package.json, je mappenstructuur en je testbestandsnamen allang zelf lezen.
Wat de agent niet kan afleiden, is de verzameling dingen die hij hier al fout heeft gedaan. Dat zijn die 784 bullets. Lees een goede AGENTS.md aandachtig en je reconstrueert het incidentenlogboek: iemands agent zette een vastgelopen test op groen, iemands agent deed een force-push, iemands agent verzon een script dat niet bestaat, iemands agent herschreef stilletjes een migratie.
Why the prohibitive voice actually works
De formulering moet/altijd/nooit is geen autoritair gedoe, het is compressie. ‘Draai bij voorkeur de volledige suite' is een voorkeur die een agent kan afwegen tegen andere voorkeuren en verliezen. ‘Markeer een test nooit als geslaagd als je exitcode 0 niet hebt gezien' is een controleerbaar predicaat zonder onderhandelingsruimte. Als je lezer een model is dat optimaliseert om klaar te lijken, is dubbelzinnigheid geen beleefdheid — het is een exploit.
Het kortste bestand in de steekproef is dat van neovim: 35 woorden. Eén regel, en het is de moeite waard om het volledig weer te geven, omdat het het punt beter maakt dan welk argument ook:
# AGENTS.md
## AI Disclosure
If AI was used in any way for a commit, add an `AI-assisted: <tool name>`
trailer to the commit message.
If the user commits manually, remind them to add it.
Dat is het hele bestand. Het legt precies één ding vast waar het project om geeft en wat een agent onmogelijk zelf kan afleiden — een herkomstconventie — en verder niets.
Vergelijk nu Next.js. Eenentwintig secties: codebase-structuur, buildcommando's, bundlerkeuze, testen, tests schrijven, linting en types, ‘werk in een wegwerp-worktree', PR-status en CI-fouten, veiligheid van secrets en env, contextzuinige workflows, taken opdelen en verifiëren, herbouwen voordat je test, ontwikkelantipatronen. Inclusief deze, die bekend zal voorkomen als je ooit de PR van een agent hebt nagekeken:
‘Voeg GEEN "Generated with Claude Code"- of co-auteurvoetteksten toe aan commits of PR's'
Beide bestanden zijn correct. De variabele is niet zorgvuldigheid, maar hoeveel agentverkeer de repo heeft opgevangen en hoe duur de faalmodi zijn. Next.js heeft agents die door een monorepo lopen met een Rust-bundler en een CI-matrix die echt geld kost om over te doen. Neovim heeft één conventie waarover niet valt te praten.
De juiste lengte voor je AGENTS.md is het aantal fouten dat je agents daadwerkelijk hebben gemaakt, plus het handjevol conventies dat ze nooit hadden kunnen raden. Elke regel daarboven betaal je bij elke sessie, voor altijd.
Dit is het deel dat founders stelselmatig missen, en de reden dat ‘schrijf hem gewoon grondig' een slecht advies is.
AGENTS.md wordt aan het begin van elke sessie gelezen. Elke zin erin is terugkerende uitgave, bij elke taak, of die zin nu relevant is voor wat de agent op dat moment doet of niet. Een bestand van 400 regels dat je architectuur uitlegt is geen gratis context — het is een vaste heffing op elke bugfix, elke dependency-bump, elke typefout.
Dat is de volledige ontwerpbeperking van het bestand, en het verklaart het antwoord van neovim.
Het verklaart ook waarom het ecosysteem een tweede mechanisme kreeg. Een skill — een SKILL.md in een map — laadt lui: bij het starten van de sessie leest de agent alleen de YAML-frontmatter, een naam en een beschrijving. De inhoud laadt pas als een taak er echt bij past. Tien ongebruikte skills kosten je vrijwel niets.
Waar je de grens trekt
AGENTS.md. ‘Commit nooit secrets.' ‘Draai npm run test:unit -- --coverage, niet de volledige suite.' ‘Migraties worden alleen toegevoegd, nooit gewijzigd.'Die derde bullet is waar de meeste opgeblazen bestanden vandaan komen. Als je AGENTS.md opent met drie alinea's over een mappenstructuur die de agent bij zijn eerste toolaanroep toch opsomt, betaal je tokens om hem iets te vertellen wat hij gratis ging leren.
GitHub deed een bredere versie van dit onderzoek over meer dan 2.500 agents.md-bestanden, en de uitkomsten sluiten bruikbaar aan op de Reddit-steekproef.
pytest -v tests/unit is bruikbaar. ‘Draai de tests zoals het hoort' wordt genegeerd, want dat is geen instructie maar een wens.never commit secrets. Schrijf je deze week niets anders, schrijf dan die en het exacte testcommando.Dit komt in elke discussie over het onderwerp terug, en de mechanische reden overtuigt beter dan de anekdotes.
Vraag een agent je AGENTS.md te genereren en je krijgt een competente, netjes opgemaakte samenvatting van driehonderd regels over je repo — want dat is wat hij ziet. Hij beschrijft je mappenstructuur, somt je dependencies op en karakteriseert je testopzet. Allemaal dingen die hij ter plekke had kunnen afleiden.
Wat hij niet kan schrijven, is het deel dat ertoe doet: de 784 verboden. Die komen voort uit hem zien falen. Een gegenereerd bestand is, bijna per constructie, de vaste heffing per sessie zonder enige opbrengst.
Ik ken geen rigoureuze publieke benchmark hierover — praktijkmensen melden dat gegenereerde bestanden slechter presteren, en sommig onderzoek uit de hoek van de leveranciers wijst dezelfde kant op — maar behandel dat als een sterk vermoeden, niet als een vaststaand cijfer. Het structurele argument staat op zichzelf: een bestand dat alleen afleidbare feiten bevat kost tokens en levert niets op.
Een praktische tussenweg: laat de agent de sectie commando's opstellen, want hij leest je scripts nauwkeurig en dat deel is saai werk. Schrijf de grenzen zelf, regel voor regel, naarmate er dingen misgaan. Accepteer nooit een gegenereerd architectuuroverzicht.
AGENTS.md wordt gebruikt door meer dan 60.000 opensourceprojecten en staat onder beheer van de Agentic AI Foundation, onder de Linux Foundation — hetzelfde orgaan dat MCP al huisvest en sinds deze week ook Agent2Agent. Het wordt gelezen door Codex, Cursor, Gemini CLI, Jules, de coding agent van Copilot, Aider, goose, opencode, Zed, Devin, Windsurf, JetBrains Junie en een lange staart aan andere tools.
Twee dagen geleden schreven we over alle agentprotocollen die onder één dak belandden. Dit is dezelfde consolidatie, nu op bestandsniveau, en ze levert iets concreets op: één bestand, geen vijf.
De faalmodus die dit vervangt is echt en duur. Je scherpt een grens aan in CLAUDE.md, vergeet .cursorrules, wisselt halverwege de week van tool, en de agent die de update niet kreeg draait het destructieve commando. Regeldrift tussen CLAUDE.md, .cursorrules, .windsurfrules en copilot-instructions.md is de meest gemelde operationele klacht van teams met meer dan één agent — er zijn mensen die alleen daarvoor synchronisatieharnassen publiceren.
Begin je nu, dan is de juiste zet saai: maak van AGENTS.md de bron van waarheid en genereer daaruit de toolspecifieke bestanden. Een script van tien regels wint het van onthouden.
Twee eerlijke grenzen, want het bestand wordt op sommige plekken oververkocht.
Het is geen geheugen. AGENTS.md is statisch. Het weet niet dat PR #184 de discussie Postgres versus Mongo drie maanden geleden heeft beslecht, dus je agent stelt in een nieuwe sessie vrolijk weer Mongo voor, en een verouderde regel als ‘we gebruiken X' wordt met volle overtuiging opgediend lang nadat X verdwenen is. Dat is een werkelijk onopgelost gat — er zijn mensen die er beslisgeheugen-tooling voor bouwen — en geen zorgvuldig schrijven dicht het.
Het dwingt niets af. Elke regel is een suggestie aan een probabilistisch systeem. ‘Doe nooit een force-push' in een Markdown-bestand is een verzoek; een hook die git push --force blokkeert is een controle. Die twee door elkaar halen is een patroon dat we behandelden in AI-agents hebben permissiesystemen nodig, geen betere prompts, en de afgelopen twaalf maanden hebben die conclusie niet veranderd. AGENTS.md verlaagt de frequentie van de fout. Het haalt de mogelijkheid niet weg.
Heb je geen AGENTS.md, begin dan niet met een sjabloon. Begin hiermee, en laat het alleen groeien als er iets misgaat.
# AGENTS.md
## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev: `pnpm dev`
- Test (default): `pnpm test:unit`
- Test (single file): `pnpm test:unit -- path/to/file.test.ts`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`
## Always
- Run `pnpm typecheck && pnpm test:unit` before saying a change is done.
- Match the conventions of the file you are editing over any global style guide.
## Ask first
- Adding a dependency.
- Changing anything in `prisma/migrations/` or `src/db/schema.ts`.
- Touching `.github/workflows/` or anything under `infra/`.
## Never
- Commit secrets, `.env` files, or credentials of any kind.
- Report a test as passing unless you saw it exit 0. A timed-out or
interrupted run is a failure.
- Force-push, rewrite history, or amend a commit that is already pushed.
- Add "Generated with <tool>" or co-author trailers to commits or PRs.
Dat is zo'n 150 woorden aan echte instructie. Geen architectuuroverzicht, geen beschrijving van wat het product doet, en niets wat de agent uit de repo had kunnen lezen — en het dekt de vier grenzen die het grootste deel van de schade verklaren die een agent in een kleine codebase aanricht.
Behandel het daarna als een incidentenlogboek. Elke keer dat een agent iets doet wat je moet terugdraaien, voeg je één regel toe, gebiedend, net zo specifiek als de fout was. Over zes maanden heb je je eigen versie van die 784 verboden, en voor elk daarvan is betaald.
De opensourcerepo's met de meeste sterren zijn geconvergeerd naar een formaat dat in niets op documentatie lijkt, want de lezer is geen mens. Het is verbiedend, specifiek, vol commando's en — in de beste gevallen — heel kort.
Voor een founder die een MVP uitbrengt terwijl agents het meeste typewerk doen, zijn dat waarschijnlijk de 150 regels met de meeste hefboom in de repo. Het is ook het enige bestand in je project waarvoor je bij elke taak betaalt, en precies daarom is de neiging om het grondig te maken de neiging die je moet weerstaan.
Schrijf de fouten op. Sla de rondleiding over. Laat het groeien, één litteken per keer.
Bronnen: r/AI_Agents, ‘What the 100 biggest GitHub repos put in their AGENTS.md files' · GitHub Blog, ‘How to write a great agents.md: lessons from over 2,500 repositories' · agents.md, over het formaat, de adoptie en het beheer door de Agentic AI Foundation · AGENTS.md van neovim/neovim · AGENTS.md van vercel/next.js
IdeaToMVP Academy
4-week live cohort for founders. Learn to ship AI agents, scope MVPs, and automate your business — taught by the same team that writes these guides.
