Wat is DESIGN.md en hoe verschilt het van AGENTS.md?

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 er in dit project gewerkt moet worden. Dit omvat het build-commando, het test-commando, de linting die moet slagen 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, zoals een tool als Claude Code of Cursor die zelfstandig uw repository leest en bewerkt, is standaard zelfverzekerd. Wanneer de agent een patroon tegenkomt 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, 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 bijbehorende HUMAN.md 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 opname-regel is één regel lang, 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 zijn documenten voor een design-systeem. 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 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 het gaat nog een stap verder. Een van de koppen is Reject generated-design reflexes. Daaronder staat een lijst van wat een capabele generator kiest 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 via reverse-engineering van openbare websites zijn verkregen. Elk bestand is geschreven volgens hetzelfde format van negen secties, zodat een agent ernaar kan worden verwezen om een vergelijkbare look te produceren. 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 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. Het zijn de bedrijven waarvan de front-end code het meest door andere ontwikkelaars wordt gekopieerd, en hun bestanden worden het werkende voorbeeld 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 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 auditlog over, en het auditlog 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 bestaat." Zonder die paragraaf voegt een agent die de opdracht krijgt de cache te versnellen Redis toe, en hij heeft gelijk om dat te doen: u heeft hem de randvoorwaarde nooit verteld. Dit is de sectie die het hele bestand rechtvaardigt.

Grenzen. De plaatsen 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 zeg wat een wijziging aan elk ervan kost.

Vocabulaire. Als de code tenant zegt en het team customer, schrijf de koppeling dan op. Een agent die hier verkeerd gokt, produceert code die goed leest maar het verkeerde modelleert; dit is het moeilijkste type fout om te ontdekken tijdens een review.

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 verworpen 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.

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 eindigt 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 gedupliceerde installatiesectie is pure overhead binnen een vastgesteld 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 uit elkaar lopen. De README stelt dat de service op 8080 luistert, DESIGN.md zegt nog steeds 3000, en de agent heeft geen manier om de ene boven de andere te verkiezen. Dus kiest hij er een en schrijft code op basis daarvan. Een bestand dat soms onjuist is, wordt geraadpleegd met hetzelfde vertrouwen 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 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 getoond: de agent hoort u te vertellen dat de taak via queue.enqueue() schrijft, omdat een directe schrijfactie het auditlogboek zou omzeilen. Als de agent 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 hebt toegevoegd en de antwoorden niet verbeteren, bevat het bestand proza dat de agent al kende. De tokentellers in Claude Code lezen 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 het gesprek van gisteren. De repository is het geheugen. Alles wat u in de chat hebt uitgelegd en nooit hebt gecommit, is bij de volgende sessie verdwenen, 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 ontwikkelingsworkflow passen, is de 2026 handleiding 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 staat onder 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 vanaf publieke sites. Beschouw het als een conventie die u nu kunt overnemen en vrij kunt uitbreiden, omdat 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 scanbaar 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 zegt wat er is besloten en wanneer. DESIGN.md zegt wat er vandaag 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 zin voorkomen had kunnen worden. Lengte is niet de maatstaf. Elke regel moet iets zijn wat de agent anders fout zou doen.