Pijn: waarom AI-code steeds op dezelfde plek struikelt

Iedereen die met Cursor, Windsurf of Claude Code bouwt, kent de frustratie: AI spuwt een hele functie uit, jij plakt hem erin — build faalt, tests worden rood, dependencies belanden op de verkeerde plek. Het probleem zit niet in de AI, maar in het feit dat het jouw projectregels niet kent.

AGENTS.md is een Markdown-bestand in de projectroot, puur voor AI. Het vertelt hoe je bouwt, test en welke stijl je aanhoudt. README.md is voor mensen: projectintro, contributiegids, merkverhaal. AI die dat leest, is als een nieuwe werknemer die op dag één een bedrijfsbrochure krijgt en meteen moet coderen — het bedrijf snapt het, maar het bouwcommando, de testflow en de ESLint-regels? Geen idee. Resultaat: jij blijft eindeloos herhalen “gebruik pnpm, niet npm”, “tests staan in packages/web”, “vergeet lint niet”. Honderd keer herhaald, en je project blijft een zooitje.

In de freelancepraktijk is de schade direct: je pakt een Next.js + Prisma-klus aan, laat Cursor meeschrijven, en de AI doet npm install — je pnpm-workspaceconfig gaat overboord. De AI kent je schema-locatie niet, de gegenereerde migration knalt eruit. Klant drukt op levering, jij debugt drie uur aan AI-code. Zo verdien je niks.

Drie klassieke valkuilen: ① verkeerde packagemanager (project draait pnpm, AI doet standaard npm install), dependencies op de foute plek, workspace werkt niet meer; ② tests niet vindbaar (tests staan in packages/web, AI draait pnpm test in de root en krijgt “geen tests gevonden”); ③ stijl die nergens bij past (ESLint + Prettier genegeerd, inspringing en quotes verkeerd, CI faalt direct).

Kans: AGENTS.md splitst “mensendocument” en “machinedocument”

Het open-source project AGENTS.md op GitHub (repo github.com/agentsmd/agents.md, circa 24.000 stars per 25-08-2026) lost dit exact op. De kern is simpel: één Markdown-bestand in de root dat AI vertelt hoe het moet bouwen, testen en stylen.

Geen vervanger van README, maar aanvulling. README bedient menselijke contributors, AGENTS.md bedient AI-agenten. Twee taken, twee bestanden, geen ruis.

Volgens de brontekst is AGENTS.md al door tienduizenden OSS-projecten omarmd (exact cijfer nog te checken). Ondersteund door VS Code, Cursor, Windsurf, Aider en GitHub Copilot (bevestigd); community noemt ook OpenAI Codex en Google Jules (⚠️ niet geverifieerd). Wie dit nu negeert, laat AI in dialect tegen zich praten.

Route 1: handmatig een minimale AGENTS.md schrijven

Kost je bijna niks. Nieuw bestand, drie blokken, klaar.

Vooraf: pnpm (schijfzuiniger dan npm, monorepo-workspace ingebouwd), turbo (taakplanner voor monorepo), --filter om alleen één subpackage aan te spreken zonder de hele repo te raken.

Blok 1 “Dev environment tips”: vertel welke packagemanager, hoe je naar een subpackage springt, hoe je een nieuwe module aanmaakt. Uit het officiële voorbeeld:

• pnpm dlx turbo run where <project_name> — spring direct naar de juiste subpackage-map, geen ls-gepruts
• pnpm install --filter <project_name> — installeer alleen deps van die subpackage, laat de rest met rust
• pnpm create vite@latest <project_name> -- --template react-ts — zet een nieuwe React + Vite + TypeScript-subpackage op

Deze commando’s raadt AI nooit zelf, maar zodra ze er staan voert AI ze klakkeloos uit.

Blok 2 “Testing instructions”: hoe draai je tests, waar zit het CI-plan, wat moet er vóór een commit draaien. Officiële voorbeeld:

• pnpm turbo run test --filter <project_name> — draai alle checks voor één subpackage
• pnpm vitest run -t "<test name>" — alleen de test met die naam
• “Fix any test or type errors until the whole suite is green” — niet stoppen voor alles groen is
• “Add or update tests for the code you change, even if nobody asked” — zonder deze regel slaat AI tests stilletjes over

Blok 3 “PR instructions”: titelformaat, verplichte lint + test. Officiële voorbeeld: Title format: [<project_name>] <Title> en “Always run pnpm lint and pnpm test before committing”.

Drie blokken, minder dan 50 regels, en de first-pass rate van AI-code schiet omhoog (community-feedback, exacte cijfers nog te checken).

Route 2: nesten in een grote monorepo

Bij enterprise-klussen draait alles in een monorepo (frontend, backend, gedeelde code in één Git-repo). Eén AGENTS.md in de root is dan te grof. AGENTS.md ondersteunt nesting: in elke subdirectory een eigen bestand, AI pakt automatisch de dichtstbijzijnde.

Praktijk: de root-AGENTS.md bevat globale regels (packagemanager, CI-flow, security). In packages/web/, packages/api/ en packages/shared/ zet je eigen bestanden met build-commando’s, test-ingangen en specifieke deps. Voorbeeld: frontend “componenten via shadcn, styling via Tailwind, iconen via lucide-react”; backend “migrations via Prisma, API-routes in src/routes, auth via JWT”.

AI pakt bij werk in een subdir automatisch de lokale AGENTS.md, met prioriteit boven de root. Frontend-AI en backend-AI krijgen zo totaal verschillende instructies zonder elkaar in de weg te zitten.

Route 3: maak er je verkoopargument van

De AI-freelancemarkt is een rode oceaan — iedereen heeft Cursor, maar de kwaliteit varieert wild. Zet in je pitch één zin: “Dit project is uitgerust met AGENTS.md, AI-ondersteunde development volgt de projectstandaard.” Dat scoort hoger dan “ik gebruik AI om te coderen”.

Werkwijze: na klusacceptatie 30 minuten de projectstructuur doorgronden, daarna een maatwerk AGENTS.md schrijven. Die doc is onderdeel van de oplevering — de klant kan er zelf mee verder als hij later AI inzet voor onderhoud.

AGENTS.md-config als aparte dienst in de etalage (richtprijzen, lokaal te kalibreren): basis €75 (enkel config-bestand + korte README), enterprise €450 (monorepo-nesting + security-sectie + teamtraining). Levering: ① maatwerk AGENTS.md ② 30 dagen chat-support ③ 10 minuten screencast-training. Past bij: klanten die al een Cursor/Windsurf-licentie hebben maar er geen rendement uithalen. Niet bij: klanten die nog puur handmatig ontwikkelen zonder AI-tools.

Case: de compatibiliteitsmuur van AGENTS.md

AGENTS.md draait onder MIT-licentie (bron bevestigd), wordt door de community onderhouden (bestuursstructuur nog te checken), website is agents.md.

De grootste troef is compatibiliteit: bevestigd voor VS Code, Cursor, Windsurf, Aider en GitHub Copilot; community noemt ook OpenAI Codex, Claude Code, Gemini CLI en Google Jules (⚠️ niet geverifieerd). Eén bestand, alle grote AI-assistenten — geen aparte config per tool.

Vergelijk: Cursor’s .cursorrules werkt alleen in Cursor, Claude Code’s CLAUDE.md alleen voor Claude, GitHub Copilot heeft weer een eigen instructiesysteem. AGENTS.md’s “write once, run everywhere” is de reden dat het zo snel is geadopteerd.

Migratiekosten naar nul. Vandaag Cursor, morgen Windsurf — AGENTS.md hergebruik je zonder herschrijven.

Call to action: vannacht nog die machinehandleiding aanleggen

5-minuten checklist: ① open je projectroot ② maak AGENTS.md ③ plak de officiële template (github.com/agentsmd/agents.md) ④ vul drie commando’s in (build, test, lint) ⑤ laat AI de volgende keer code schrijven en kijk wat er gebeurt.

Draai je een monorepo, besteed dan vanavond 20 extra minuten aan nesting per subpackage. Morgenochtend zul je merken dat AI-code niet meer eindeloos correctie nodig heeft.

AGENTS.md is op dit moment de hoogste ROI in AI-coding-config: 30 minuten werk, maandelijks uren debug-tijd terug.