Wat is een DESIGN.md bestand voor AI-codeeragenten?

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

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

Een codeeragent, zoals een tool als 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 datastore), 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, was 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 opnamecriteria bestaan uit één regel, en die regel vormt 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 voorbeelden zijn documenten voor een design-systeem. Ze beschrijven hoe een product eruit moet zien: kleur, typografie, witruimte, beweging. Kijk voorbij de inhoud, want het nuttige deel is de structuur van de tekst in plaats van het onderwerp 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 een stap verder. Een van de koppen is Reject generated-design reflexes. Daaronder staat een lijst van wat een capabele generator kiest wanneer niemand heeft aangegeven dat dit niet mag:

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 genereert, gepubliceerd zodat het model stopt met het produceren daarvan. 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 er eerder bij. awesome-design-md bevat 73 bestanden die zijn reverse-engineered van openbare websites. Elk bestand is geschreven volgens hetzelfde formaat van negen secties, zodat een agent naar één bestand kan worden verwezen om iets te produceren dat die look benadert. Die 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 schaal voor typografie wijzigt, 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 ook zijn eigen 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 wie die zeven zijn. Dit zijn de bedrijven waarvan de front-end code het meest door andere ontwikkelaars wordt gekopieerd, en hun bestanden worden het uitgewerkte voorbeeld van wat een DESIGN.md is. Vergelijk het pad dat AGENTS.md heeft afgelegd: agents.md telt inmiddels meer dan 60.000 open source projecten die het formaat gebruiken, en het beheer ligt bij de Agentic AI Foundation onder de Linux Foundation. Conventies voor door agents leesbare bestanden vestigen zich snel, en ze vestigen 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 de 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 audit-log over, en het audit-log is wat de compliance-export leest." Een invariant met de bijbehorende reden overleeft contact met een taak die u nooit had voorzien. Een invariant op zichzelf 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 heeft de randvoorwaarde nooit vermeld. 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 ze en vermeld wat een wijziging aan elk ervan kost. Als de agent ook het open web kan bereiken, bijvoorbeeld via een zelfgehoste SearXNG-instantie die is gekoppeld als zoek-backend, dan is dat een grens die ook het vermelden waard is. 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 leesbaar is maar het verkeerde model hanteert. Dat is het lastigste type fout om tijdens een review op te merken.

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 het hoofd kunt schrijven, invarianten en afgewezen alternatieven, en laat de rest als koppen staan. Een bestand met vier eerlijke regels volstaat. Een bestand met veertig gegokte regels niet. Als de repository meerdere pakketten bevat, zal één root-bestand niet voor allemaal voldoen. Dezelfde splitsing per map die werkt voor geneste AGENTS.md-bestanden in een monorepo is hier van toepassing: een kort root-bestand voor de beslissingen die voor alles gelden, en een kleiner bestand naast elk pakket dat zijn eigen beslissingen heeft.

Sommige tools laden elk markdown-bestand in de root van de repository en andere laden alleen het bestand dat expliciet wordt opgegeven, dus ga hier 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

Architectuurbeslissingen

Openstaande vragen

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

De meest voorkomende slechte versie leest prettig, maar leert de lezer niets. Het 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 daarvan verklaart waarom de zaken zijn ingericht zoals ze zijn.

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 meest waardevolle tekst in de repository zijn.

De tweede kostenpost is ernstiger. Twee kopieën van dezelfde verklaring gaan uit elkaar lopen. De README zegt dat de service op 8080 luistert, 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 snel. Als een alinea prima in de README zou passen, schrap deze dan uit DESIGN.md. Wat overblijft, moet het deel zijn dat u hardop zou uitspreken tijdens een code review, het deel dat begint met "dat hebben we al geprobeerd".

Hoe weet u of het bestand werkt?

Er is geen linter hiervoor. Er is echter 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 getoond: 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 tekst die de agent al kende. Het lezen van de tokentellers in Claude Code laat zien waar dat budget naartoe gaat.

Dit is vooral van belang 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 bij de volgende sessie verdwenen, en DESIGN.md is de plek waar die uitleg thuishoort zodat deze behouden blijft.

Begin bij 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 het toe aan het bestand wanneer het misgaat, niet volgens een vast schema. Als u nog aan het uitzoeken bent waar agents in een normale ontwikkelingsworkflow 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 gebruikt door meer dan 60.000 open-sourceprojecten 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 first-party adoptie: zeven bedrijven, waaronder Vercel, Nuxt, Atlassian en Resend, publiceren er een op een openbare URL, en een community-verzameling bevat er nog 73 die zijn reverse-engineered vanaf openbare websites. 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, wat zeldzamer is en zwaarder weegt. Voeg bij een splitsing één regel toe aan AGENTS.md waarin u de agent instrueert 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 volledig 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 dit is het bestand waarnaar u de agent verwijst.

Hoe lang moet een DESIGN.md zijn?

Kort genoeg om zonder bezwaar bij elke beurt te 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 dat 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.