developer.overheid.nl

Ontwikkelaarsportaal van de Nederlandse overheid

Ga naar hoofdinhoud

AGENTS.md

AGENTS.md is een markdownbestand in de root van een repository met instructies voor AI-assistenten die aan het project werken. Waar README.md de mens uitlegt wat het project is, legt AGENTS.md de assistent uit hoe hij zich hoort te gedragen.

Het formaat wordt beheerd door de Agentic AI Foundation onder de Linux Foundation en is ontstaan uit samenwerking tussen verschillende leveranciers van ontwikkeltooling. Meer dan twintig tools lezen het bestand, waaronder Cursor, Gemini CLI, GitHub Copilot, Claude Code, VS Code, Zed en Aider.

Waarom het bestaat​

Zonder zo'n bestand legt iedere ontwikkelaar in elke sessie opnieuw uit hoe je de tests draait, welke conventies gelden en waar de assistent vanaf moet blijven. Dat is herhaald werk, en het resultaat verschilt per persoon.

Met een bestand in de repository staan die afspraken op één plek, in versiebeheer, zichtbaar voor het hele team, en gelden ze ongeacht wie er werkt.

Wat erin hoort​

Er zijn geen verplichte velden; het is gewone markdown. In de praktijk komen deze onderdelen terug:

  • Wat het project is, in een paar zinnen
  • Bouwen en testen: de commando's, letterlijk
  • Conventies: naamgeving, taal, bestandsstructuur
  • Wat je niet moet aanraken: gegenereerde bestanden, vendor-mappen, migraties
  • Security: wat nooit in de code hoort

Schrijf op wat een assistent niet uit de code kan afleiden. Dat het project TypeScript gebruikt, ziet hij zelf. Dat jullie een pnpm-workspace hebben waar npm install stuk op gaat, niet.

Een voorbeeld​

# AGENTS.md

Docusaurus-site voor het ontwikkelaarsportaal van de Nederlandse overheid.

## Bouwen en testen

- Installeren: `pnpm install --frozen-lockfile`
- Lokaal draaien: `pnpm start`
- Volledige build: `pnpm build` (controleert ook interne links)
- Formatteren: `pnpm exec prettier --write .`

## Conventies

- Klantfacing tekst in het Nederlands, code en variabelen in het Engels
- Artikelen krijgen `content_type` in de frontmatter
- Interne links relatief, niet absoluut

## Niet aanraken

- `build/` en `.docusaurus/` zijn gegenereerd
- `pnpm-lock.yaml` alleen via pnpm zelf

Nesten​

Een AGENTS.md in een submap gaat voor op die in de root. In een monorepo kun je zo per package aanvullende afspraken vastleggen zonder de root te vervuilen.

Verhouding tot CLAUDE.md​

CLAUDE.md is de variant van Claude Code en bestond eerder dan AGENTS.md. Ze doen hetzelfde en hebben dezelfde vorm; het verschil is dat AGENTS.md leveranciersneutraal is en breder wordt gelezen.

Voor een nieuw project is AGENTS.md de logische keuze: één bestand dat door de meeste tools wordt begrepen. Heb je al een CLAUDE.md, dan is de eenvoudigste route hem hernoemen. Wie beide wil ondersteunen, kan er een symlink van maken, zodat de inhoud niet op twee plekken uiteen kan lopen.

Aandachtspunten​

Het bestand staat in versiebeheer en is openbaar zodra de repository dat is. Zet er dus geen secrets of interne URL's in die niet naar buiten mogen.

Bedenk ook dat iedereen die naar de repository kan schrijven, de instructies van de assistent kan aanpassen. Bij een project met externe bijdragers hoort een wijziging in AGENTS.md net zo goed gereviewd te worden als een wijziging in de code.

Meer weten​