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 hoofdmap 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 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, 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 eigenlijk in een gepubliceerd DESIGN.md-bestand

De snelste manier om de indeling te leren kennen, is de bestanden te lezen die bedrijven over zichzelf publiceren. De repository official-design-md houdt alleen deze bestanden bij. De inclusieregel bestaat uit één regel, en juist die regel vormt het belangrijkste punt van deze verzameling:

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

In oktober 2026 bevat de lijst er elf: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel en VoltAgent. Elk bestand staat op een openbare URL, meestal op het eigen domein van de uitgever en voor de rest in een openbare GitHub-repository. U kunt er dus nu één in een terminal lezen.

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

Beide bestanden zijn documenten voor een designsysteem. Ze beschrijven hoe een product eruit moet zien: kleur, typografie, witruimte en animatie. Kijk voorbij het onderwerp, want het nuttige deel is de vorm van de tekst en niet het onderwerp zelf.

Het Nuxt-bestand telt op 27 oktober 2026 ongeveer 2.000 woorden. Het grootste deel bestaat uit een regel met de reden erbij. Het begint met de mededeling dat de donkere modus het standaardthema is. Het noemt het merkgroen #00DC82 met de opmerking dat de merkkleuren bedoeld zijn voor "Logo's, afbeeldingen voor sociale media en drukwerk. Gebruik ze niet als onbewerkte waarden in UI-code." Aan het einde bevat een sectie met de kop Reject these het volgende:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Het Vercel-bestand is langer, ongeveer 6.000 woorden volgens de stand van oktober 2026, en gaat nog een stap verder. Een van de koppen luidt Reject generated-design reflexes. Daaronder staat een lijst met wat een capabele generator gebruikt 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 met de standaardinstellingen die een zelfverzekerd model produceert, gepubliceerd zodat het model ermee ophoudt die te produceren. Elk DESIGN.md-bestand dat het vastleggen waard is, bevat voor een bepaald domein zo'n lijst.

Waarom publiceren bedrijven hun eigen DESIGN.md?

De community was er als eerste bij. awesome-design-md bevat 84 bestanden die uit openbare websites zijn gehaald, volgens de telling in de README op 27 oktober 2026. Elk bestand gebruikt dezelfde indeling met negen secties, zodat u een agent ernaar kunt verwijzen en iets kunt laten produceren dat sterk op die stijl lijkt. Deze bestanden zijn nuttig, maar het blijven inschattingen. Niemand bij de beoordeelde bedrijven heeft ze gecontroleerd.

Een bestand van de organisatie zelf is anders, omdat het de bron is en niet een interpretatie van het resultaat. Wanneer Vercel zijn typografische schaal wijzigt, wijzigt vercel.com/design.md mee. Een kopie die in maart is gescrapet, blijft uw agent de oude schaal aanleren. Niets in uw repository meldt dat de kopie verouderd is.

Elf uitgevers is nog steeds een klein aantal, en de repository vermeldt dat ook: de standaard is nieuw en de officiële toepassing ervan groeit. Beide verzamelingen worden onderhouden door VoltAgent, een open source agentframework dat ook een eigen bestand publiceert. Beschouw de lijst daarom als een tracker en niet als een neutrale telling. De lijst is toch de moeite waard om te volgen vanwege de organisaties die erin staan. Verschillende daarvan zijn bedrijven waarvan andere ontwikkelaars de front-endcode het vaakst kopiëren. De nieuwere vermeldingen, Ant Design, Microsoft FAST, Juspay en Oxide Computer, zijn designsystemen waarop andere teams voortbouwen. Hun bestanden worden steeds meer het uitgewerkte voorbeeld van wat een DESIGN.md is. Vergelijk het pad dat AGENTS.md heeft afgelegd: agents.md telt nu meer dan 60,000 open source-projecten die de indeling gebruiken, en het beheer ligt bij de Agentic AI Foundation onder de Linux Foundation. DESIGN.md is dezelfde weg ingeslagen. Op 21 april 2026 maakte Google een conceptspecificatie voor de indeling open source. Deze is gepubliceerd als google-labs-code/design.md, met een tokenschema en een CLI onder de Apache-2.0-licentie. In oktober 2026 bevindt de indeling zich op versie alpha en wordt deze nog actief ontwikkeld. Google Labs beheert de indeling in plaats van een neutrale stichting, en de indeling beschrijft een visuele identiteit. Daarom zegt zij niets over de invarianten die een backendbestand nodig heeft. Conventies voor bestanden die door agents kunnen worden gelezen, krijgen snel vorm. Die vorm komt van bovenaf.

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 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 heeft 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 ze en geef aan wat een wijziging aan elk daarvan 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 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 wordt 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 goed 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 volstaat. Een bestand met veertig gegokte regels niet. Als de repository meerdere pakketten bevat, zal één root-bestand niet voor allemaal werken. De splitsing per map die werkt voor geneste AGENTS.md-bestanden in een monorepo is hier ook 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 sommige laden alleen het bestand dat expliciet is opgegeven, 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 sluit af met de licentie. Elke regel daarvan staat al in de README, en niets ervan legt uit waarom 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 opnieuw in rekening gebracht, en een dubbele 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 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 voorrang heeft. Dus kiest de agent er 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 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 schrijft via queue.enqueue(), omdat een directe schrijfactie het auditlogboek zou overslaan. Als de agent een databaseverbinding opent en schrijft, is een van de twee volgende zaken 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 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 met de beslissingen waarover u discussieert

De eerste versie kost twintig minuten. Open de laatste paar pull requests waarin een reviewer schreef "nee, we doen het 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 dezelfde manier als AGENTS.md. AGENTS.md heeft een officiële thuisbasis op agents.md, wordt gebruikt door meer dan 60,000 opensourceprojecten en valt onder het beheer van de Agentic AI Foundation, onderdeel van de Linux Foundation. DESIGN.md heeft wel een gepubliceerde specificatie, maar geen neutrale beheerder. Google heeft op 21 april 2026 een concept van de specificatie als opensourceproject gepubliceerd. Het staat in de repository google-labs-code/design.md onder de Apache-2.0-licentie. In oktober 2026 heeft het versie alpha en is het nog volop in ontwikkeling. Het beschrijft een visuele identiteit: kleuren, typografie, lay-out en componenten. DESIGN.md wordt ook door de oorspronkelijke ontwikkelaars toegepast: elf bedrijven en projecten, waaronder Vercel, Nuxt, Atlassian en Resend, publiceren zo'n bestand. Daarnaast bevat een communitycollectie op 27 oktober 2026 nog 84 exemplaren die uit openbare sites zijn verzameld. Voor een backendbestand met invarianten en afgewezen alternatieven kunt u het zien als een conventie die u nu kunt invoeren en vrij kunt uitbreiden. Geen enkele specificatie schrijft deze sectienamen namelijk voor.

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

Voor een kleine repository: ja. Eén bestand dat de agent zeker leest, is beter dan twee bestanden waarvan er één wordt genegeerd. Splits de bestanden wanneer AGENTS.md niet meer snel te scannen 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 na het splitsen één regel toe aan AGENTS.md waarin u de agent opdraagt DESIGN.md te lezen voordat de agent code bewerkt. Niet elke tool laadt namelijk elk markdownbestand in de root.

Waarin verschilt DESIGN.md van een architecture decision record?

Een ADR (architecture decision record) is een gedateerde vastlegging van één beslissing. Een goed onderhouden project verzamelt daar tientallen van in een map. Dat is geschiedenis. Geschiedenis is duur om te laden, omdat een agent ze allemaal zou moeten lezen om vast te stellen welke beslissingen nog gelden. DESIGN.md beschrijft de huidige toestand en is bedoeld om bij elke taak volledig te worden gelezen. Houd beide bij als u al ADR's schrijft. De ADR vermeldt wat wanneer is besloten. DESIGN.md vermeldt wat vandaag waar is. Naar dat bestand verwijst u de agent.

Hoe lang moet een DESIGN.md zijn?

Kort genoeg om het bij elke beurt zonder bezwaar te laden. De gepubliceerde voorbeelden zijn lang omdat ze een volledige visuele taal specificeren: het bestand van Nuxt bevat ongeveer 2,000 woorden en dat van Vercel ongeveer 6,000, beide gemeten in oktober 2026. Een backendservice heeft doorgaans veel minder nodig. Begin met één pagina. Breid het bestand alleen uit wanneer een agent iets verkeerd doet dat met één zin had kunnen worden voorkomen. De lengte is niet de maatstaf. Elke regel moet iets beschrijven wat de agent anders verkeerd zou doen.