Wat is een DESIGN.md bestand voor AI coding agents?

Wat DESIGN.md is en wat AGENTS.md niet dekt

DESIGN.md is een markdown-bestand in de root van uw repository dat een AI-coding agent uitlegt waarom de code op een bepaalde manier is gestructureerd. AGENTS.md beantwoordt een andere vraag: hoe hier gewerkt moet worden. Dit omvat het build-commando, het test-commando, de lint-regels waaraan voldaan moet worden en de paden die ongemoeid moeten blijven. DESIGN.md legt de beslissingen vast die al zijn genomen en wat er kapotgaat wanneer een van deze beslissingen wordt teruggedraaid.

Een coding agent, oftewel een tool zoals Claude Code of Cursor die zelfstandig uw repository leest en bewerkt, is standaard zelfverzekerd. Wanneer de agent een patroon vindt dat hij niet herkent, probeert hij dit te verbeteren. Een handgeschreven cache wordt dan bijvoorbeeld Redis (een in-memory data store), omdat dat is hoe een cache eruitziet in het merendeel van de code die het model heeft gelezen. AGENTS.md voorkomt dit niet, omdat make test in beide gevallen slaagt. De regel die werd overtreden, stond nergens opgeschreven waar de agent deze kon lezen.

Als u het eerste bestand nog niet heeft geschreven, begin daar dan. AGENTS.md en de HUMAN.md die ernaast staat behandelt het formaat en waar elke tool ernaar zoekt. Wat volgt is het hoofdstuk dat daarop aansluit.

Wat staat er daadwerkelijk in een gepubliceerde DESIGN.md

De snelste manier om het formaat te leren kennen, is door de bestanden te lezen die bedrijven over zichzelf publiceren. De repository official-design-md houdt alleen deze bij. De opnameregel is één regel lang, en die regel is de kern van de hele verzameling:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

Per augustus 2026 staan er zeven in de lijst: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel en VoltAgent. Elk bestand bevindt zich op een stabiele publieke URL, dus u kunt er direct een lezen in een terminal.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Beide documenten zijn designsystemen. Ze beschrijven hoe een product eruit moet zien: kleur, typografie, witruimte, beweging. Kijk voorbij het onderwerp, want het nuttige deel is de vorm van de tekst in plaats van de inhoud zelf.

Het bestand van Nuxt bevat ongeveer 2.100 woorden, en het grootste deel daarvan is een regel met de bijbehorende reden:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Het bestand van Vercel is langer, ongeveer 6.500 woorden in augustus 2026, en gaat nog een stap verder. Een van de koppen is Reject generated-design reflexes. Daaronder staat een lijst van wat een capabele generator pakt wanneer niemand hem heeft opgedragen dat niet te doen:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Die zin definieert het bestandstype. Het is een geschreven lijst van de standaardinstellingen die een zelfverzekerd model produceert, gepubliceerd zodat het model stopt met het produceren ervan. Elke DESIGN.md die het waard is om vast te leggen, is zo'n lijst voor een specifiek domein.

Waarom publiceren bedrijven hun eigen DESIGN.md?

De community was hen voor. awesome-design-md bevat 73 bestanden die zijn reverse-engineered van openbare websites. Elk bestand is geschreven volgens hetzelfde format van negen secties, zodat een agent ernaar kan worden verwezen om een vergelijkbare lay-out te genereren. Deze bestanden zijn nuttig, maar het blijven gissingen. Niemand bij de betreffende bedrijven heeft ze gecontroleerd.

Een first-party bestand is anders omdat het de bron is in plaats van een interpretatie van de output. Wanneer Vercel zijn typografische schaal aanpast, verandert vercel.com/design.md mee. Een kopie die in maart is gescraped, blijft uw agent de oude schaal aanleren, en niets in uw repository zal u vertellen dat de kopie verouderd is.

Zeven uitgevers is een klein aantal, en de repository vermeldt dit ook: de standaard is nieuw en de officiële adoptie groeit. Beide collecties worden onderhouden door VoltAgent, een open-source agent-framework dat zelf ook een bestand publiceert. Lees de lijst daarom als een tracker en niet als een neutrale inventarisatie. Het is desondanks de moeite waard om deze te volgen, vanwege de identiteit van de zeven partijen. Het zijn de bedrijven waarvan de front-end code het meest door andere ontwikkelaars wordt gekopieerd, en hun bestanden worden het praktijkvoorbeeld van wat een DESIGN.md is. Vergelijk het pad dat AGENTS.md heeft bewandeld: agents.md telt inmiddels meer dan 60.000 open-source projecten die het format gebruiken, en het beheer ligt bij de Agentic AI Foundation onder de Linux Foundation. Conventies voor door agents leesbare bestanden vormen zich snel, en ze vormen zich vanuit de top.

Wat hoort er in een DESIGN.md als het project geen gebruikersinterface heeft

De meeste software die op een VPS draait, heeft geen visuele taal om te specificeren. Het bestand is desondanks nuttig, omdat het mechanisme niets met kleur te maken heeft. Het gaat om het vastleggen van randvoorwaarden die een zelfverzekerde editor anders ongemerkt zou schenden.

Invarianten. Eén zin per stuk, waarin iets wordt gesteld dat na elke wijziging waar moet blijven. "Elke schrijfactie verloopt via queue.enqueue(). Een directe database-schrijfactie slaat het auditlog over, en het auditlog is wat de compliance-export uitleest." Een invariant met de bijbehorende reden overleeft contact met een taak die u nooit had voorzien. Een losse invariant leest als een voorkeur, en voorkeuren worden weggeoptimaliseerd.

Verworpen alternatieven. De voor de hand liggende optie, en waarom deze is afgewezen. "We gebruiken geen Redis voor caching. De service draait op een enkele VPS, dus een in-process map is sneller en het is één daemon minder om in de lucht te houden. Heroverweeg dit wanneer er een tweede applicatieserver bijkomt." Zonder die paragraaf voegt een agent die de opdracht krijgt de cache te versnellen Redis toe, en dat is terecht: u had de randvoorwaarde niet gecommuniceerd. Dit is de sectie die het hele bestand rechtvaardigt.

Grenzen. De plekken waar een kleine wijziging een grote impact heeft. Het databaseschema. Het publieke route-prefix waar klanten al scripts tegenaan hebben draaien. Het configuratiebestand dat een deploy leest voordat de applicatie start. De cron-entry die ervan uitgaat dat er slechts één kopie van draait. Benoem deze en vermeld wat een wijziging aan elk ervan kost. Als de agent ook het open internet kan bereiken, bijvoorbeeld via een zelfgehoste SearXNG-instantie gekoppeld als zoek-backend, dan is dat ook een grens die het waard is om op te schrijven. Het bestand moet namelijk aangeven welke opgehaalde tekst de code mag beïnvloeden en welke tekst alleen aan u mag worden teruggegeven.

Vocabulaire. Als de code tenant zegt en het team customer, leg de koppeling dan vast. Een agent die hier verkeerd gokt, produceert code die prima leest maar het verkeerde modelleert. Dat is het lastigste type fout om tijdens een review te ontdekken.

Een DESIGN.md die u vandaag kunt kopiëren

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Vul de twee secties in die u vandaag uit uw hoofd kunt schrijven, invarianten en afgewezen alternatieven, en laat de rest als koppen staan. Een bestand met vier eerlijke regels werkt. Een bestand met veertig gegokte regels niet.

Sommige tools laden elk markdown-bestand in de root van de repository en sommige laden alleen het bestand dat expliciet wordt aangewezen, dus ga daar niet vanuit. Voeg een verwijzing toe naar AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

Invarianten

Afgewezen alternatieven

Systeemarchitectuur

Datamodellen

Beveiligingsimplicaties

Het anti-patroon: een DESIGN.md die de README herhaalt

De meest voorkomende slechte versie leest prettig, maar leert de lezer niets. Het document opent met wat het project doet, somt de functies op, legt de installatie uit en sluit af met de licentie. Elke regel daarvan staat al in de README, en niets ervan verklaart waarom zaken op een bepaalde manier zijn ingericht.

Dat kost u dubbel. De eerste kostenpost is context. Een bestand dat de agent aan het begin van elke taak leest, wordt bij elke taak in rekening gebracht, en een dubbele installatiesectie is pure overhead binnen een vast venster. Het beheren van dat venster is een vaardigheid op zich, die wordt behandeld in het beheren van het contextvenster in Claude Code. De korte versie: alles wat automatisch wordt geladen, moet de tekst met de hoogste waarde in de repository zijn.

De tweede kostenpost is erger. Twee kopieën van dezelfde verklaring gaan na verloop van tijd uit elkaar lopen. De README zegt dat de service luistert op 8080, DESIGN.md zegt nog steeds 3000, en de agent heeft geen manier om te bepalen welke informatie correct is. Hij kiest er dus een en schrijft code op basis daarvan. Een bestand dat soms onjuist is, wordt met hetzelfde vertrouwen geraadpleegd als een bestand dat altijd juist is.

De test is eenvoudig. Als een alinea prima in de README zou passen, schrap deze dan uit DESIGN.md. Wat overblijft, moet het gedeelte zijn dat u hardop zou uitspreken tijdens een code review, het gedeelte dat begint met "dat hebben we al geprobeerd".

Hoe stelt u vast dat het bestand werkt?

Er is geen linter hiervoor. Er is wel een controle die u binnen een minuut kunt uitvoeren.

Geef de agent een taak die direct ingaat op een invariant. "Voeg een achtergrondtaak toe die verouderde rijen als verlopen markeert." Een bestand dat zijn werk doet, komt in het antwoord naar voren nog voordat er code wordt geschreven: de agent hoort u te vertellen dat de taak schrijft via queue.enqueue(), omdat een directe schrijfactie het auditlogboek zou omzeilen. Als het een databaseverbinding opent en schrijft, is een van de twee waar. Het bestand wordt helemaal niet gelezen, of de invariant is vaag genoeg geformuleerd om over te discussiëren.

Houd ook het aantal tokens in de gaten, aangezien dit bestand bij elke beurt wordt geladen. Als het contextgebruik stijgt nadat u DESIGN.md heeft toegevoegd en de antwoorden niet verbeteren, bevat het bestand proza dat de agent al kende. Het uitlezen van de tokentellers in Claude Code laat zien waar dat budget naartoe gaat.

Dit is het belangrijkst wanneer de agent op een server draait in plaats van op uw laptop. Een agent die in een langlopende sessie werkt, zoals de configuratie in een Claude Code-werkruimte op een VPS met tmux, heeft geen geheugen van de conversatie van gisteren. De repository is het geheugen. Alles wat u in de chat heeft uitgelegd en nooit heeft gecommit, is verdwenen bij de volgende sessie, en DESIGN.md is de plek waar die uitleg thuishoort zodat deze behouden blijft.

Begin met de beslissingen waarover u discussieert

De eerste versie kost twintig minuten. Open de laatste paar pull requests waarin een reviewer schreef "nee, dat doen we hier anders". Elk van die opmerkingen is een invariant die nooit is vastgelegd, en elk punt is een plek waar een agent dezelfde fout zal maken, sneller en vaker dan een mens zou doen. Voeg deze toe aan het bestand wanneer het misgaat, niet volgens een vast schema. Als u nog aan het uitzoeken bent waar agents in een normale ontwikkelworkflow passen, is de 2026 gids voor het leren werken met AI-agents een logische volgende stap.

FAQ

Is DESIGN.md een officiële standaard?

Niet op de manier waarop AGENTS.md dat is. AGENTS.md heeft een thuisbasis op agents.md, wordt door meer dan 60.000 open source-projecten gebruikt en valt onder het beheer van de Agentic AI Foundation, onderdeel van de Linux Foundation. DESIGN.md heeft per augustus 2026 geen bestuursorgaan en geen gepubliceerde specificatie. Wat het wel heeft, is adoptie door de bron zelf: zeven bedrijven, waaronder Vercel, Nuxt, Atlassian en Resend, publiceren er een op een publieke URL, en een community-verzameling bevat er nog eens 73 die zijn reverse-engineered van publieke sites. Beschouw het als een conventie die u nu kunt overnemen en vrij kunt uitbreiden, aangezien niets uw sectienamen valideert.

Moet DESIGN.md gewoon een sectie van AGENTS.md zijn?

Voor een kleine repository wel. Eén bestand dat de agent gegarandeerd leest, is beter dan twee bestanden waarvan er één wordt genegeerd. Splits ze wanneer AGENTS.md niet langer overzichtelijk is, of wanneer u merkt dat de twee helften in een verschillend tempo veranderen. AGENTS.md verandert wanneer de build verandert. DESIGN.md verandert wanneer een beslissing verandert; dat gebeurt minder vaak en heeft meer gewicht. Voeg bij een splitsing één regel toe aan AGENTS.md waarin u de agent opdraagt om DESIGN.md te lezen voordat er code wordt bewerkt, omdat niet elke tool elk markdown-bestand in de root laadt.

Hoe verschilt DESIGN.md van een architecture decision record?

Een ADR (architecture decision record) is een gedateerd verslag van één beslissing, en een gezond project verzamelt er tientallen van in een map. Dat is een geschiedenis, en geschiedenis is kostbaar om te laden, aangezien een agent ze allemaal zou moeten lezen om te achterhalen welke nog steeds geldig zijn. DESIGN.md is de huidige status, geschreven om bij elke taak in zijn geheel te worden gelezen. Houd beide bij als u al ADR's schrijft. De ADR vermeldt wat er is besloten en wanneer. DESIGN.md vermeldt wat vandaag de dag waar is, en dat is het bestand waarnaar u de agent verwijst.

Hoe lang moet een DESIGN.md zijn?

Kort genoeg om bij elke beurt zonder spijt te kunnen laden. De gepubliceerde voorbeelden zijn lang omdat ze een volledige visuele taal specificeren: het Nuxt-bestand bevat ongeveer 2.100 woorden en het Vercel-bestand ongeveer 6.500 per augustus 2026. Een backend-service heeft meestal veel minder nodig. Begin met één pagina en breid deze alleen uit wanneer een agent iets fout doet wat met één enkele zin voorkomen had kunnen worden. Lengte is niet de maatstaf. Elke regel moet een punt zijn dat de agent anders fout zou doen.