---
title: Je design system agent-ready maken
description: >-
  Geef een coding agent context, constraints en een verificatie-loop, zodat hij
  minder verkeerde afslagen neemt in je design system.
language: Dutch
url: 'https://www.voorhoede.nl/nl/blog/je-design-system-agent-ready-maken/'
---

Blog

# Maak je design system agent-ready

By [Sjoerd](/nl/team/sjoerd.md)

30 June 2026

* [De agent context geven](#de-agent-context-geven)
* [Skill files](#skill-files)
* [MCP's](#mcp-s)
* [claude.md](#claude-md)
* [Constraints](#constraints)
* [Werk vanuit een vast palet](#werk-vanuit-een-vast-palet)
* [Houd wijzigingen klein](#houd-wijzigingen-klein)
* [Stop in plaats van verzinnen](#stop-in-plaats-van-verzinnen)
* [Verificatie-loop](#verificatie-loop)
* [Checks op codeniveau](#checks-op-codeniveau)
* [Visual regression](#visual-regression)
* [Sluit de loop zo vroeg mogelijk](#sluit-de-loop-zo-vroeg-mogelijk)
* [Tot slot](#tot-slot)

Een design system is een van de betere plekken om een coding agent aan het werk te zetten. Of dat werk ook goed gebeurt, hangt af van wat je eromheen bouwt.

De code van een design system leent zich meestal goed voor werk door een agent. Er zijn duidelijke, gedocumenteerde regels om te volgen en genoeg componenten om als voorbeeld te gebruiken. Waarschijnlijk levert het bruikbare resultaten op zonder veel extra sturing. Maar zoals we allemaal weten neemt de agent af en toe een verkeerde afslag, maakt iets onbegrijpelijks, bouwt daarop verder, en druk je zo snel mogelijk op de revert-knop. Deze blog gaat over het verkleinen van de kans dat de agent zo'n verkeerde afslag neemt.

Wat we willen doen is de agent context, grenzen en een verificatie-loop meegeven. Die kunnen uit agent-specifieke configuratie komen (skills, rules, claude.md), maar net zo goed uit de documentatie die het UX/Design-team opzet. In deze blog lopen we deze drie patronen langs en laten we met voorbeelden zien hoe je ze opzet, inclusief voorbeelden die je zo in je instructiebestanden kunt plakken.

*Let op: de voorbeelden gebruiken Claude Code, omdat we dat bij De Voorhoede vooral gebruiken. De concepten werken net zo goed in andere tools zoals Cursor, Copilot of Codex.*

## De agent context geven

Kies bij het inrichten van je agent het juiste mechanisme op basis van scope:

* **Skills**: voor specifieke, taakgerichte workflows (ingeladen wanneer de taak erom vraagt).
* **MCP's**: voor toegang tot externe tools (handig wanneer de agent informatie nodig heeft of een actie moet uitvoeren).
* **claude.md**: voor conventies die voor het hele project gelden (elke sessie ingeladen).
* **Rules**: voor constraints op bestandsniveau (geladen wanneer een pad matcht).

| Mechanisme | Scope             | Belangrijkste gebruik       |
| ---------- | ----------------- | --------------------------- |
| Skills     | Taakgericht       | Specifieke workflows        |
| MCPs       | Extern            | Toegang tot live data/tools |
| claude.md  | Hele project      | Globale conventies          |
| Rules      | Bestandsspecifiek | Pad-gebonden constraints    |

Een agent probeert zelf de juiste context te verzamelen. Dat kunnen relevante bestanden en online bronnen zijn, maar er zijn manieren om hem specifieke bronnen te laten gebruiken.

## Skill files

Skill files zijn kleine instructies die een agent laten zien hoe hij een specifieke taak consistent uitvoert. Je kunt ze installeren met een tool als [skills.sh](https://www.skills.sh/), of ze zelf schrijven of genereren.

De opbouw van een skill file ziet er zo uit:

```
---
name: my-skill
description: What this skill does and when to use it.
---
# Skill title
Instructions for the agent go here.
```

De agent verzamelt alle skills in het project, zet hun descriptions in zijn context en bepaalt welke skills volledig meegenomen moeten worden. Die worden vervolgens toegevoegd aan de context om tot een beter antwoord te komen. Een skill kan ook uit meerdere bestanden bestaan die in een indexbestand genoemd worden, om de informatie op te splitsen. De agent neemt dan alleen de relevante bestanden uit dat indexbestand mee voor de taak waar hij mee bezig is.

In de context van een design system zou een 'create-react-component'-skill er zo uit kunnen zien. Om deze skill effectief te maken verwijzen we expliciet naar een skill met React-conventies. De stappen in de workflow staan in een vaste volgorde: door eerst de kernconventies af te dwingen voorkom je dat de agent afdwaalt, en door vroeg de integriteit van tokens te borgen stop je drift voordat het ontstaat.

```
---
name: create-react-component
description: Create or update a single design-system component using approved tokens and vercel-react-best-practices (an installed skill for React conventions).
---
# Create React Component

## Purpose
Use this skill when implementing a design-system component.

## Required workflow
1. Use `vercel-react-best-practices` to inherit existing React architecture rather than improvising.
2. Use only tokens from the `tokens` package to maintain visual consistency.
3. Reuse existing patterns and keep the change small to ensure easier reviews.

## Token rules
- Do not hardcode design values.
- If a required token is missing, report the gap instead of inventing one.

## React rules
- Follow `vercel-react-best-practices` for React and Next.js implementation.
- Keep the component accessible and avoid unnecessary complexity.

## Output expectations
- List the files changed.
- Summarize the token choices.
- Note how `vercel-react-best-practices` was applied.
```

Wanneer de gebruiker de agent vraagt om een nieuw component te maken, komt hij deze description tegen en neemt hij de volledige inhoud op in zijn context. Hij ziet ook dat hij de 'vercel-react-best-practices'-skill nodig heeft, leest die skill en neemt de relevante delen mee in de context.

Je kunt allerlei skills toevoegen of genereren voor je codebase. Een paar voorbeelden:

* **docs-sync**: werkt usage-docs, props-tabellen, voorbeelden en do/don't-richtlijnen bij wanneer het component verandert.
* **token-audit**: controleert of een component goedgekeurde tokens gebruikt voor spacing, kleur, typografie en motion.
* **accessibility-review**: zoekt naar ontbrekende labels, focus-states, toetsenbordondersteuning en contrastproblemen.

## MCP's

Met instructies alleen kom je maar tot een bepaald punt. Vaak is het nuttiger om de agent directe toegang te geven tot de systemen die je team toch al gebruikt.

Daar worden MCP-servers (Model Context Protocol) interessant. Een MCP-server laat een agent externe systemen bevragen en gestructureerde informatie ophalen terwijl hij werkt.

Voor een design system kunnen handige integraties zijn:

* Figma, om componentspecificaties, variabelen en design tokens op te halen.
* Storybook, om bestaande componenten en implementatievoorbeelden te ontdekken.
* Chromatic of andere visual-regression-tooling, om visuele wijzigingen te valideren.
* Component-registries en package-documentatie, om te begrijpen welke bouwblokken er zijn.

In plaats van een component in een prompt te beschrijven, haalt de agent de actuele source of truth direct uit de tool. Dat scheelt documentatie die je anders in je instructiebestanden moet dupliceren, en verkleint de kans dat je met verouderde informatie werkt.

## claude.md

Zie dit als een readme.md voor agents. Het vertelt AI-agents hoe ze in jouw project moeten werken: build- en test-commando's, code-stijl, architectuur, conventies en alles wat een nieuwe collega zou moeten weten. Behandel het als een levend document en werk het bij zodra je iets ontdekt dat toekomstige agents helpt om beter bij te dragen.

Een kort voorbeeld van hoe dit eruit kan zien in je design system:

```
# Project Agent Guide

## Build & Test
- Run `pnpm build`, `pnpm test`, and `pnpm lint` before finishing meaningful changes.

## Style
- Follow the existing patterns and structure in the repo.
- Keep changes small, focused, and minimal.

## Conventions
- Use the existing component and file layout instead of inventing new structures.

## When Unsure
- Ask before making breaking changes or inventing new patterns and values.
```

Rules zijn instructies die alleen voor specifieke delen van je codebase gelden. Anders dan claude.md, dat elke sessie geladen wordt, en skills, die geladen worden wanneer ze relevant zijn voor een taak, wordt een rule pas geladen wanneer de agent met bestanden werkt die matchen met het ingestelde pad-patroon.

Daarmee zijn rules ideaal voor richtlijnen die maar voor een deel van de repository relevant zijn. In plaats van claude.md vol te zetten met package-specifieke details, houd je instructies dicht bij de code waar ze over gaan.

Rules zijn vooral waardevol in monorepo's, waar verschillende packages of libraries hun eigen architectuur, codestandaarden, testeisen of deployment-workflows kunnen hebben. Door instructies aan specifieke paden te koppelen krijgen agents de context die ze nodig hebben, zonder afgeleid te worden door dingen die er niet toe doen.

Maak rules als Markdown-bestanden in .claude/rules/, met één onderwerp per bestand. Elke rule heeft een paths-veld in de frontmatter dat bepaalt waar hij geldt.

```
---
paths:
  - "packages/**/*.stories.{tsx,ts}"
  - "apps/docs/**/*.mdx"
---
# Documentation rules
- Every component has a usage page covering: when to use it, when not to, and at least one live example.
- Keep prop tables generated from the component's types, not handwritten — if they drift, fix the source, not the table.
- Each example is copy-pasteable and uses approved tokens, never hardcoded values.
- Pair every "do" example with the matching "don't" so the guidance shows both sides.
- Write guidance for the consumer of the component, not its author. No internal implementation detail.
```

Houd er rekening mee dat de volledige inhoud aan de context wordt toegevoegd zodra een matchend bestand wordt aangeraakt.

Een paar rules die handig zouden zijn in je design system:

* Een tokens-rule met scope packages/tokens/\*\*, die het naamschema beschrijft en aangeeft dat elke token een light- en een dark-waarde nodig heeft.
* Een docs-rule met scope op je MDX- of Storybook-bestanden, die het do/don't-formaat beschrijft en eist dat props-tabellen synchroon blijven met het component.
* Een changeset-rule met scope packages/\*\*, die de agent eraan herinnert dat een wijziging in een publieke API een changeset-entry nodig heeft.

## Constraints

Alles hierboven is een instructie. De agent leest het en volgt het meestal op, maar kan het ook negeren. Voor de meeste constraints is dat prima, maar je belangrijkste constraints zijn het waard om ze lastiger te maken om te overtreden. Constraints liggen op een spectrum van gevraagd tot afgedwongen. Je kunt de agent vragen om alleen bestaande tokens te gebruiken, of je geeft hem een API waarin al het andere simpelweg niet compileert:

```
// Asked: a rule says "only use approved variants"
// Enforced: the wrong variant doesn't typecheck
type ButtonProps = {
  variant: "primary" | "secondary" | "ghost";
};
```

Naast het toevoegen van context om te verrijken wat de agent weet, is het ook belangrijk om te vertellen wat hij niet kan en niet mag doen. Zo zijn er minder verkeerde afslagen om überhaupt te nemen.

## Werk vanuit een vast palet

Laat de agent werken met wat er al is in plaats van nieuwe dingen te verzinnen. Voorbeelden van goede constraints:

* Gebruik alleen tokens uit de tokens-package. Hergebruik bestaande componenten en primitives voordat je iets nieuws bouwt.
* Haal geen nieuwe dependencies binnen.
* Introduceer geen nieuwe abstractie of patroon als een bestaande past.

Om de agent deze regels te laten volgen, zet je ze in je claude.md:

```
# Constraints
- Only use tokens from the `tokens` package. No raw hex, px or ad-hoc values.
- Compose from existing components before writing new markup.
- No new dependencies without flagging it first.
- Don't invent new patterns when one already exists in the repo.
```

## Houd wijzigingen klein

De tweede constraint gaat over scope. Een kleine, gerichte wijziging is makkelijk te reviewen en snel terug te draaien.

* Raak één component per wijziging aan.
* Refactor geen code die geen onderdeel is van de taak.
* Verander geen publieke API en bewerk geen gegenereerde bestanden zonder het eerst aan te geven.

Een kleine diff houdt de agent ook eerlijk. Hoe meer hij mag aanraken, hoe meer ruimte hij heeft om af te dwalen van wat je eigenlijk vroeg.

## Stop in plaats van verzinnen

Wanneer de agent iets tegenkomt dat ontbreekt (een token die niet bestaat, een patroon dat hij niet kan vinden, een onduidelijke eis), zou de default moeten zijn om te stoppen en het gat te melden, niet om er met giswerk langs te improviseren.

Een agent die een eenmalige #3a3a3a verzint omdat geen enkele token matchte, is precies de verkeerde afslag die je probeert te voorkomen. Door de agent te laten melden dat er iets ontbreekt en jou erbij te halen, verander je die stille fout in een vraag die je daadwerkelijk kunt beantwoorden.

Een voorbeeld van hoe zo'n instructie eruit kan zien:

```
## When unsure
- If a required pattern or component is missing, report the gap.
- If the request is ambiguous, ask before choosing.
- Prefer doing less and flagging it over doing more and guessing.
```

## Verificatie-loop

Linten, testen en QA zijn altijd al een belangrijk onderdeel van softwareontwikkeling geweest. Ze zijn goed in het opmerken van een verkeerde afslag en kunnen je meestal vertellen wat het resultaat was en wat er werd verwacht. Voor een agent telt niet alleen dat hij die checks kan draaien, maar ook dat hij de output helder kan lezen.

## Checks op codeniveau

De basis-loop draait op de tools die je al hebt. Typecheck, lint, tests en build geven allemaal een duidelijk signaal waar de agent op kan reageren.

```
## Verify before finishing
- Run `pnpm typecheck`, `pnpm lint`, and `pnpm test`.
- Fix anything that fails and run them again.
- Don't finish while a check is still red.
```

## Visual regression

Alle tests kunnen slagen terwijl het component visueel nog steeds niet klopt met het ontwerp. Juist in een design system is visual-regression-testing de manier om die loop te sluiten. Het maakt een baseline-screenshot en vergelijkt die met latere aanpassingen. Je kunt dit opzetten met een headless browser zoals [Playwright](https://playwright.dev/) of met visual-testing-tools zoals [Chromatic](https://www.chromatic.com/).

Wat hier telt, is de feedback-loop. De agent kan een pixel-diff niet letterlijk zien, dus hij is afhankelijk van de harness om die diff om te zetten in iets leesbaars: een percentage veranderde pixels, een pass/fail per snapshot, of een screenshot met onderschrift die terug de sessie in gaat. Geef hem dat en hij kan zelf beoordelen of de wijziging bedoeld was of een regressie die je beter kunt terugdraaien. Laat je het weg, dan draait de agent de check, krijgt een afbeelding terug die hij niet kan lezen, en is hij niets wijzer dan daarvoor.

## Sluit de loop zo vroeg mogelijk

De waarde van de loop zit in hoe vroeg hij draait. Een check die pas in CI afgaat, vertelt de agent tien minuten en één context-switch te laat dat hij fout zat. Diezelfde check, in de sessie en na elke wijziging, laat hem zichzelf ter plekke corrigeren.

Breng de verificatie dus zo dicht mogelijk bij het werk, maar stem elke check af op hoe zwaar of traag hij is om te draaien. Typecheck en lint zijn vrijwel direct, dus die kan de agent na elke wijziging draaien. Visual regression start een browser op, dus die draai je beter één keer als een component af lijkt dan na elke edit. Volledige builds en end-to-end-flows zijn te traag voor de inner loop, dus die kunnen wachten op een laatste gate of CI. Snellere feedback fixt meer verkeerde afslagen vanzelf, maar niet elke check hoort in elke loop en in een design system blijft zelfs de trage kant enigszins licht, omdat we toch geen site-brede end-to-end-flows draaien.

## Tot slot

Een mooi neveneffect van dit alles: elke plek waar de agent in de war raakt, is meestal een plek die ook voor mensen al onduidelijk was. Een nieuwe collega was tegen diezelfde ontbrekende token of dat onduidelijke patroon aangelopen, alleen had die het iemand gevraagd in plaats van te gokken. Dingen goed inrichten voor de agent fixt die gaten meteen voor iedereen.

Je hoeft dit dus niet allemaal vooraf op te schrijven. De volgende keer dat de agent iets geks doet en je naar de revert knop beweegt, behandel het als een hint over wat er ontbreekt: een stukje context, een constraint die je nooit hebt opgeschreven, of een check die de loop niet had. Voeg dat ene ding toe en de volgende run gaat net wat beter.

[← All blog posts](/nl/blog.md)

[Return to top](#top)