Wat is AGENTS.md en hoe schrijf je in 30 minuten je eigen bestand?

Praktische materialen over vibe coding en werken met agents: Ailoot-documentatie.

AGENTS.md in één alinea#

Hieronder wordt het formaat besproken aan de hand van agents.md, de documentatie van OpenAI Codex, JetBrains Junie, Cursor Rules Docs, het wijzigingenlogboek van GitHub Copilot Coding Agent en het persbericht van de Linux Foundation over de Agentic AI Foundation. Alle cijfers en functies zijn actueel per 30 mei 2026. De ondersteuning van AGENTS.md in Claude Code wordt beschreven aan de hand van de documentatie van Anthropic, bijgewerkt op 24 september 2026.

Heb je geen idee wat deze dierentuin aan tools op de markt is of waarom die een gedeeld bestand nodig heeft, lees dan eerst de gids “Waarmee codeer je in 2026: 8 AI-tools, van Claude Code tot Antigravity”. Dit artikel gaat specifiek over het AGENTS.md-formaat en hoe je in 30 minuten je eigen bestand schrijft.

Wat is AGENTS.md en waar komt het vandaan?#

Voorheen had elke AI-tool een eigen bestand met regels: Anthropic had CLAUDE.md, Cursor had .cursorrules, GitHub had .github/copilot-instructions.md, Aider had .aider.conf.yml en JetBrains had .junie/guidelines.md. Als je team drie verschillende agents gebruikte, betekende dat drie parallelle bestanden met dezelfde inhoud, die binnen een week van elkaar zouden afwijken.

OpenAI was de eerste die daar genoeg van had. In augustus 2025 bracht het Codex CLI uit en lanceerde het tegelijk agents.md als open formaat. Van de website:

“Zie AGENTS.md als een README voor agents.”

(agents.md, vertaald uit het Engels)

Deze standaardregel geldt voor clients die dit zoek- en voorrangsmechanisme werkelijk implementeren. Controleer de geïnstalleerde versie; bij expliciet ingesteld laden kan een ander bestandspad gelden.

Het belangrijkste punt is dat AGENTS.md een aanvulling is op README. README is geschreven voor mensen: “wat het project is, hoe je het lokaal uitvoert en hoe je eraan kunt bijdragen.” AGENTS.md is geschreven voor de agent: exacte shellcommando’s, controleerbare criteria voor wanneer iets “klaar” is en grenzen zoals “raak dit nooit aan”.

Van de website:

“AGENTS.md vult README aan: het bevat aanvullende, soms gedetailleerde context die de agent nodig heeft — bouwstappen, tests en conventies die README te vol zouden maken of die menselijke bijdragers eenvoudigweg niet nodig hebben.”

(agents.md, vertaald uit het Engels)

In september 2025 ondersteunde GitHub Copilot Coding Agent het formaat (wijzigingenlogboek, 28.08.2025). In december waren Cursor, Junie, Gemini CLI, Aider en nog een tiental tools aangesloten. Op 9 december 2025 richtte de Linux Foundation de Agentic AI Foundation (AAIF) op. De drie oprichtingsprojecten waren OpenAI’s AGENTS.md, Anthropic’s MCP en Block’s goose. De oprichtende leden waren AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft en OpenAI. Op 24 februari 2026 telde de stichting al 146 organisaties, waaronder Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath en Hitachi.

Vanaf dat moment was AGENTS.md niet langer “weer iets van OpenAI”, maar werd het de facto een standaard.

Welke AI-agents lezen AGENTS.md en welke niet?#

Ondersteuningstabel per 30 mei 2026; de rij voor Claude Code is bijgewerkt op 24 september 2026:

Anthropic was de laatste van de grote spelers die meedeed. In augustus 2025 werd in de officiële repository anthropics/claude-code issue #6235 geopend met een verzoek om ondersteuning voor AGENTS.md.

De issue bleef bijna een jaar open en werd op 17 augustus 2026 gesloten; versie 2.1.277 met ondersteuning voor AGENTS.md verscheen op 18 september. Anthropic hanteert de volgende logica: CLAUDE.md heeft voorrang, en AGENTS.md wordt gelezen als er geen CLAUDE.md staat in de werkmap of een bovenliggende map. Volgens de documentatie werkt het als volgt:

Het addertje onder het gras: een persoonlijke CLAUDE.local.md telt ook mee, en daardoor stopt Claude Code met het lezen van AGENTS.md. Je kunt dit gedrag wijzigen in /config, onder Project instructions — bijvoorbeeld zodat Claude Code beide bestanden tegelijk leest. In versies ouder dan 2.1.277 wordt AGENTS.md niet automatisch opgepikt; de regel @AGENTS.md in CLAUDE.md blijft dan de workaround.

Waarin verschilt AGENTS.md van CLAUDE.md en .cursorrules?#

Vergelijking van de vier formaten per 30 mei 2026:

De kern is: AGENTS.md kan regels delen als iedere client correct is gekoppeld; persoonlijke instellingen die je niet commit blijven een afzonderlijk probleem. Claude Code heeft daarvoor CLAUDE.local.md, Cursor heeft lokale .mdc-bestanden onder de gebruiker. AGENTS.md biedt dat op zichzelf niet; je moet het combineren met andere bestanden of als team afspreken om persoonlijke regels in secties te zetten die door gitignore worden uitgesloten.

Een ander belangrijk detail zijn monorepo’s. Codex en Cursor volgen de regel “de dichtstbijzijnde AGENTS.md wint”:

“Zet in een monorepo een aparte AGENTS.md in elk pakket. Agents lezen automatisch het dichtstbijzijnde bestand in de mapstructuur; het dichtstbijzijnde bestand wint.”

(agents.md, vertaald uit het Engels)

Volgens agents.md bevat OpenAI’s belangrijkste monorepo 88 AGENTS.md-bestanden voor verschillende subpakketten. Werk je in een monorepo, verdeel de regels dan over de niveaus: algemene regels in de hoofdmap, specifieke regels in submappen.

Wat hoort er in een goede AGENTS.md?#

De website agents.md biedt een flexibel formaat — “elke Markdown”. Maar 80% van de goede bestanden die in het wild voorkomen, bevatten dezelfde acht secties. De hoofdregel: elk item moet een exact commando of concreet voorbeeld zijn. Een abstract idee als “schrijf schone code” wordt door de agent genegeerd.

1. Projectoverzicht — 2–3 regels. Wat het project is, voor wie het bedoeld is en wat het hoofddoel is. Geen marketing. Voorbeeld: “Telegram-bot voor onboarding bij een betaalde workshop. Stack: Next.js 14, Prisma, PostgreSQL. Wordt gestart wanneer er een nieuw record in purchases verschijnt.”
2. Installatie- en configuratieopdrachten — exacte shellcommando’s om lokaal uit te voeren. npm install, npm run dev, npm run build. Geen “zo doen we het meestal”.
3. Codestijl / conventies — specifieke regels met een voorbeeld, niet “schrijf netjes”. Bijvoorbeeld: “TypeScript strict, enkele aanhalingstekens, geen default exports, componentnamen in PascalCase, hooks beginnen met use.”
4. Tips voor de ontwikkelomgeving — waar belangrijke dingen staan. Welke variabelen nodig zijn in .env, waar geheimen worden opgeslagen, welke poorten in gebruik zijn en hoe je met de lokale database werkt.
5. Testinstructies — hoe je een specifieke test uitvoert en wat als “geslaagd” telt. Bijvoorbeeld: npm test -- --testPathPattern=user-auth; 100% moet slagen.
6. PR- / commitrichtlijnen — formaat van commitberichten, checklist vóór een PR (tests, linter, documentatie) en wie de goedkeuring geeft.
7. Veiligheidsoverwegingen — wat nooit mag gebeuren. “Commit .env nooit. Geheimen horen alleen in Vault. Toon geen persoonlijke gegevens van gebruikers in logs.”
8. Grenzen / Doe dit nooit — verboden handelingen met een alternatief. “Gebruik geen git push --force op main. Als je moet terugdraaien, gebruik git revert of git reset op een feature branch.”

Gebruik voor elke sectie het principe “commando in plaats van idee”. De agent negeert “wees voorzichtig met migraties”. De agent volgt wel “Voer vóór alembic upgrade head alembic check uit. Als er een fout verschijnt, pas de migratie dan niet toe en vraag het mij.”

Kant-en-klaar AGENTS.md-sjabloon (kopieer en pas aan)#

# AGENTS.md

## Projectoverzicht

<project-name> - <één zin die het doel beschrijft>.
Stack: <Next.js / Python / Go / ...>.
Belangrijkste entiteiten: <gebruikers, bestellingen, berichten ...>.
Details voor mensen staan in README.md.

## Installatie- en configuratieopdrachten

```bash
# eerste installatie
npm install
cp .env.example .env  # vul daarna handmatig in; zie de lijst hieronder

# uitvoeren
npm run dev           # ontwikkelserver op :3000
npm run build         # productiebuild
npm run start         # productiebuild uitvoeren
```

## Ontwikkelomgeving

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 lokaal op :5432 (`docker-compose up postgres`)
- Redis is optioneel en alleen nodig voor queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Lees nooit het volledige `.env`-bestand. Als je één variabele nodig hebt: `grep "^VAR=" .env`

## Codestijl

- TypeScript strict mode
- Enkele aanhalingstekens, geen puntkomma’s (tenzij ESLint ze vereist)
- Imports: eerst extern, dan intern via `@/`, daarna relatief
- Componenten in PascalCase; hooks beginnen met `use`
- Gebruik geen `any` zonder een expliciete opmerking die uitlegt “waarom dit niet getypeerd kan worden”

Voorbeeld van een goede module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testen

```bash
npm test                                # alle tests
npm test -- --testPathPattern=auth      # alleen auth
npm test -- --watch                     # watchmodus
```

Alle tests moeten slagen voordat je commit. Is een test mislukt, commit dan niet; vraag mij wat je moet doen.

## Richtlijnen voor pull requests

- Commitformaat: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Vóór de PR: `npm run build && npm test && npm run lint`
- PR-beschrijving = wat verandert, waarom en hoe je het test
- Keur je eigen PR niet goed — wacht altijd op beoordeling door een mens

## Beveiliging

- Geheimen uitsluitend in `.env` en Vault, nooit in code
- Log geen persoonlijke gegevens (e-mail, telefoon, naam)
- Gebruik bij het werken met de productiedatabase alleen leesopdrachten, tenzij je daar expliciet toestemming voor hebt
- Hardcode geen API-sleutels van externe diensten (Stripe, OpenAI) in tests

## Doe dit nooit

- Gebruik geen `git push --force` naar main. Als je moet terugdraaien, gebruik `git revert` of open een nieuwe PR
- Voer geen databasemigraties uit zonder `alembic check` (of het equivalent in je ORM)
- Gebruik geen `npm install -g` of `sudo` voor projectafhankelijkheden
- Voeg geen afhankelijkheden toe zonder toestemming (vooral geen zware: webpack-plug-ins, ORM)

Het sjabloon is gemiddeld 80–120 regels lang. Als het bestand meer dan 150 regels bevat, is dat een teken dat je het moet herstructureren: verplaats iets naar docs/, verwijs ernaar of vat het samen in één regel. In de praktijk werken bestanden van 100–150 regels het best; daarna beginnen de kwaliteitswinsten om te slaan.

Welke 5 regels maken AGENTS.md echt nuttig?#

1. Commando’s in plaats van ideeën. Een agent begrijpt “wees voorzichtig met migraties” niet. De agent volgt wel alembic check vóór alembic upgrade head. Agents werken met commando’s en voorwaarden, niet met stemmingen. Formuleer alle belangrijke regels als “doe X, anders Y”.

2. Verboden met een alternatief. Een kale “doe geen force push” wordt na twee of drie prompts stilletjes genegeerd door de agent. De combinatie “doe X niet; doe in plaats daarvan Y” werkt wel. Voorbeeld: “Gebruik geen git push --force op main; gebruik git revert of open een nieuwe PR als je moet terugdraaien.”

3. Precies één bron van waarheid. De AGENTS.md in de hoofdmap is de bron van waarheid voor het hele project. Gebruik je een monorepo, gebruik dan geneste AGENTS.md-bestanden in submappen volgens de regel “de dichtstbijzijnde wint”. Geen parallelle bestanden met tegenstrijdige instructies.

4. Controleerbare criteria voor “klaar”. “Tests moeten slagen” is nutteloos. Een exact criterium is: npm test geeft exitcode 0 en schrijft geen FAIL naar stdout. “De code moet netjes zijn” is ook nutteloos. Een exact criterium is: npm run lint slaagt zonder waarschuwingen. Een agent begrijpt pas wat “klaar” betekent als je de voorwaarde expliciet beschrijft.

5. Een bestand van minder dan 150 regels. Boven de 150 regels beginnen de meetwaarden terug te lopen: de agent besteedt meer context aan lezen en mist belangrijke regels. Past het niet, verplaats de details dan naar docs/architecture.md en verwijs er vanuit AGENTS.md naar. Laat in het bestand alleen commando’s en grenzen staan.

Welke 10 fouten maken AGENTS.md waardeloos?#

1. Vage regels zonder commando’s. De agent negeert “wees voorzichtig met migraties” — die zin zegt hem niets. Alleen een specifiek commando met een voorwaarde werkt: “Voer vóór alembic upgrade head alembic check uit. Pas bij een fout de migratie niet toe en vraag het mij.”

2. “Schone code.” Een nutteloze uitdrukking. Vervang die door een concreet patroon: “Gebruik functionele componenten met hooks. Voorbeeld: function LoginForm() { const [email, setEmail] = useState(''); ... }”

3. Ongestructureerde tekst. Als AGENTS.md 300 regels proza zonder koppen bevat, besteedt de agent 80K contexttokens aan irrelevante passages en mist hij wat ertoe doet. Gebruik H2/H3-koppen, korte secties en opsommingen.

4. Een bestand van meer dan 150 regels. Kwaliteitsmetingen verslechteren boven deze grens. Splits het op in een hoofdbestand met verwijzingen naar details in docs/.

5. 30+ verboden zonder alternatieven. Als het bestand een lange lijst bevat met “doe X niet, doe Y niet” zonder uit te leggen “doe in plaats daarvan Z”, tast de agent blind rond.

6. README.md dupliceren. Heb je al in README geschreven “hoe je installeert en uitvoert”, kopieer dat dan niet naar AGENTS.md. Verwijs in plaats daarvan in één regel naar README en beschrijf in AGENTS.md wat de agent nodig heeft, maar menselijke bijdragers niet.

7. Geheimen hardcoden. AGENTS.md kan openbaar zijn (het staat in git). Zet er geen echte API-sleutels, tokens of wachtwoorden in. Verwijs alleen naar opslagplaatsen voor geheimen: “Zie Vault: secret/staging/db.”

8. Conflicterende prioriteiten zonder rangorde. “Werk snel” + “houd 90% testdekking” laat de agent twijfelen wat hij moet kiezen. Rangschik de prioriteiten expliciet: “Testdekking ≥80% eerst, daarna snelheid. Als ze botsen, gaan tests voor.”

9. Verouderde documentatie. Een architectuurbeschrijving vermeldt REST+polling terwijl de werkelijkheid inmiddels WebSockets is. De agent volgt de verouderde beschrijving en breekt de architectuur. Regel: werk AGENTS.md bij in dezelfde PR als de code wanneer de architectuur verandert.

10. Te veel architectuur voor een eenvoudige taak. Als iemand vraagt om twee regels in een configuratie te wijzigen, moet de agent niet de volledige topologie van 14 microservices hoeven lezen. Verplaats de diepgaande architectuur naar docs/architecture.md; laat in AGENTS.md alleen staan: “Lees docs/architecture.md als de taak over architectuur gaat.”

Het onderzoek van GitHub Blog onder meer dan 2,500 AGENTS.md-repositories trekt deze hoofdconclusie:

“De meeste agentbestanden mislukken omdat ze te algemeen zijn. ‘Je bent een behulpzame programmeerassistent’ werkt niet.”

(GitHub Blog, vertaald uit het Engels)

Hoe houd je AGENTS.md en CLAUDE.md in één repository?#

De belangrijkste praktische vraag is hoe je beide bestanden naast elkaar gebruikt zonder inhoud te dupliceren. Er zijn drie scenario’s:

Scenario 1: alleen Claude Code. Behoud CLAUDE.md en gebruik alle functies van Claude Code: ~/.claude/CLAUDE.md voor instructies op gebruikersniveau, CLAUDE.md voor het project, CLAUDE.local.md voor persoonlijke aanpassingen, @import om andere bestanden op te nemen en .claude/skills/ voor gespecialiseerde skills. AGENTS.md is niet nodig.

Scenario 2: meerdere programmeerclients. Bewaar gedeelde regels in AGENTS.md en koppel en controleer iedere client afzonderlijk. Gemini CLI ondersteunt een ingestelde contextbestandsnaam; Aider kan een bestand via zijn leesconfiguratie laden. Dat zijn expliciete laadmethoden, geen identieke automatische detectie.

Start een nieuwe sessie in een onschadelijke testrepository. Voeg een unieke, onschuldige instructie toe, zoals “neem de markering instructions-loaded op in het testantwoord”, en controleer behalve het antwoord ook de gedocumenteerde lijst met geladen bestanden of de logs van de client. Herhaal dit voor iedere client en versie die je gebruikt. Een gegenereerde bewering dat het bestand is gelezen is geen onafhankelijk laadbewijs; één geslaagde controle bewijst geen ondersteuning in alle andere tools.

Scenario 3: een gemengd team (Claude Code + andere tools). Dit is in 2026 de meest voorkomende configuratie. Maak AGENTS.md het primaire bestand. Heb je geen regels die alleen voor Claude Code gelden, maak dan helemaal geen CLAUDE.md aan: sinds versie 2.1.277 leest Claude Code AGENTS.md als er geen CLAUDE.md in het project staat. Heb je zulke regels wel, maak dan van CLAUDE.md een symlink of een korte wrapper met de import @AGENTS.md.

Bekijk beide bestanden en maak een back-up voordat je ze wijzigt. Bestaan beide, voeg dan niet-conflicterende gedeelde instructies in AGENTS.md samen en behoud Claude-specifieke instructies in CLAUDE.md met een @AGENTS.md-import. Behoud bestaande symlinks in plaats van ze te vervangen.

Voor een gewone CLAUDE.md, alleen als AGENTS.md ontbreekt, weigert deze macOS/Linux-shellcontrole een bestaand doel of symlink te overschrijven:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

Na een geslaagde hernoeming is CLAUDE.md een symlink naar AGENTS.md. Alle agents die AGENTS.md lezen, zien dezelfde inhoud. Claude Code, dat CLAUDE.md leest, ziet via de symlink dezelfde inhoud.

Op Windows vereist het maken van een symlink Developer Mode (of Admin), wat voor het hele team onhandig kan zijn. Een alternatief is een korte CLAUDE.md die AGENTS.md importeert:

# CLAUDE.md

@AGENTS.md

## Specifiek voor Claude Code

- Gebruik .claude/skills/ voor gespecialiseerde prompts
- Raadpleeg bij het werken met Skills .claude/skills/INDEX.md
- Gebruik Plan Mode vóór grote wijzigingen (Shift+Tab)

In Claude Code haalt deze syntaxis AGENTS.md met één regel binnen en voegt eronder specifieke extra’s voor Claude Code toe. Wil je AGENTS.md later verwijderen, dan hoef je alleen de import te verwijderen. Deze regel leidt niet tot dubbel lezen: volgens de documentatie van Claude Code wordt hetzelfde AGENTS.md-bestand niet twee keer geladen, ook niet als Claude het zelfstandig kan lezen.

Aanbevolen indeling voor een team met meerdere tools in 2026:

repo-root/
├── AGENTS.md                              # bron van waarheid, ≤150 regels
├── CLAUDE.md                              # alleen met specifieke Claude-regels: symlink → AGENTS.md OF @AGENTS.md + extra’s
├── .cursor/rules/                         # gerichte aanpassingen, alleen voor Cursor
├── .github/copilot-instructions.md        # “Zie AGENTS.md”, indien gebruikt
└── docs/architecture.md                   # uitgebreide architectuur waarnaar AGENTS.md verwijst

Meer over CLAUDE.md lees je in de gids “CLAUDE.md goed configureren”. Lees voor meer context over waarom een agent een groot instructiebestand nodig heeft “Wat is context engineering?”.

Wat veranderde er in 2026: waarom bracht AAIF AGENTS.md onder bij de Linux Foundation?#

Het belangrijkste politieke verhaal in AI-programmeren in mei 2026 was niet de release van een nieuw model, maar de consolidatie van formaten. Voorheen had elke leverancier zijn eigen bestand met regels. Dat was handig voor leveranciers, maar lastig voor teams die met meerdere tools werkten.

In een persbericht van 9 december 2025 kondigde de Linux Foundation de Agentic AI Foundation aan als koepel voor drie formaten:

• AGENTS.md van OpenAI — een bestandsformaat met instructies voor agents
• Model Context Protocol (MCP) van Anthropic — een protocol om externe tools met agents te verbinden
• goose van Block — een open-source agentframework

Uit het persbericht van de Linux Foundation:

“Door deze projecten onder de paraplu van de AAIF samen te brengen, kunnen ze zich ontwikkelen met de transparantie en stabiliteit die alleen open bestuur biedt.”

(Persbericht van de Linux Foundation, 9 december 2025, vertaald uit het Engels)

Op 24 februari 2026 waren 146 organisaties lid van de AAIF (97 nieuwe leden in twee maanden). De nieuwe Gold-leden waren onder meer Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express en Autodesk. Anthropic is Platinum-lid en promoot MCP. OpenAI is Platinum-lid en promoot AGENTS.md. Block is Platinum-lid met goose.

Dit verandert de positie van AGENTS.md: van “een OpenAI-formaat” naar een industriestandaard. In het voorjaar van 2026 stond Claude Code nog aan de zijlijn, maar in september leerde het met versie 2.1.277 AGENTS.md zelfstandig lezen. CLAUDE.md is niet verdwenen en heeft standaard nog steeds voorrang als het in het project staat.

Een praktisch begin is gedeelde projectregels in AGENTS.md, aangevuld met de import, wrapper of expliciete leesconfiguratie die iedere gebruikte client nodig heeft. Controleer bij Claude Code de geïnstalleerde versie en bestandsvoorrang voordat je een CLAUDE.md-import of symlink kiest. Verifieer het laden in iedere client; hier is geen dekkingspercentage vastgesteld.

Wat volgt?#

AGENTS.md is de eerste bouwsteen voor “afspraken maken met een agent zodat die voorspelbaar werkt”. De tweede bouwsteen is een kennismap van het project, met zakelijke context, doelgroep, producten en prijzen. De derde bouwsteen is context engineering, dat alles samenbrengt: welke bestanden de agent bij elke stap ziet, hoe de status tussen sessies wordt bewaard en hoe je tussen verschillende modellen wisselt.

Praktische materialen: Ailoot-documentatie.

Meer materialen en tools: Ailoot.