Praten met je code: zo maakt Modelith domeinmodellen levend

Laten we eerlijk zijn — de meeste projecten beginnen met goede bedoelingen. Iemand tekent het domeinmodel op een whiteboard, iedereen knikt, en dan... sterft het stilletjes in een Confluence-pagina die niemand meer bijwerkt.

Het probleem zit niet in het idee van domeinmodelleren zelf. Het zit in hoe domeinmodellen meestal worden behandeld:

• Eenmalig opgesteld en daarna vergeten
• Apart bijgehouden van de code
• Alleen leesbaar in specifieke tools
• Moeilijk automatisch te controleren

Modelith pakt dit anders aan. In plaats van je domeinmodel te zien als een oplevering die je archiveert, behandelt het het als een levend iets dat naast je code leeft, geschreven wordt door middel van gesprekken, en automatisch wordt gevalideerd in je CI-pipeline.

Wat is een domeinmodel eigenlijk?

Laten we eerst even hetzelfde niveau krijgen. Een domeinmodel is je conceptuele kaart van het systeem — de zelfstandige naamwoorden (entiteiten), hun onderlinge relaties, en de regels die alles besturen. Het is geen databaseschema of API-specificatie. Het is de canonische, eenvoudige uitdrukking van wat je systeem doet.

Denk eraan als de gedeelde taal van je hele team. Als iedereen uit hetzelfde model leest, worden gesprekken scherper, gaat onboarding sneller, en het opzetten van nieuwe services of features voelt minder aan als archeologisch graafwerk in oude code.

De Modelith-werkwijze: Beschrijf, Schets, Valideer, Genereer

Hier wordt het interessant. Met Modelith schrijf je geen YAML direct. Je denkt niet eens na over YAML. Je beschrijft je domeinconcepten gewoon in gewone taal aan een AI-agent (specifiek: een Claude Code-skill), en de agent schetst de onderliggende YAML voor je.

Het proces ziet er zo uit:

1. Beschrijf — Je praat over je domein in gewoon Engels. "We hebben klanten die orders kunnen plaatsen, orders bevatten meerdere producten, maar klanten kunnen maximaal drie actieve orders hebben."

2. Schrijf — De Claude Code-plugin vertaalt je beschrijving naar een modelith.yaml-bestand, met directe validatie.

3. Valideer — Draai modelith lint om volledigheid en consistentie te controleren. Dit wordt je CI-poort.

4. Genereer — Draai modelith render om Markdown te maken met Mermaid-diagrammen. Commit dit samen met de YAML.

De gegenereerde Markdown is leesbaar voor mensen zonder speciale tools. De YAML is de machine-leesbare bron van waarheid. En CI zorgt ervoor dat ze nooit uit elkaar lopen — vergelijk het met een gegenereerde-code-check, maar dan voor je domeinmodel.

Waarom deze aanpak werkt

Gewone taal verlaagt de drempel

Niet iedereen op je team voelt zich comfortabel bij JSON Schema of UML-diagrammen. Maar iedereen kan gewone Engels lezen. Door gewone taal als startpunt te nemen, maakt Modelith domeinmodelleren toegankelijk voor iedereen. Je productmanager kan bijdragen. Je QA-engineer kan het controleren. Je junior developer kan daadwerkelijk het grotere plaatje begrijpen.

AI neemt het saaie werk uit handen

YAML met de hand schrijven is foutgevoelig en, eerlijk is eerlijk, saai. Door een AI-agent de vertaling van je beschrijving naar geldige YAML te laten doen, haal je de cognitieve belasting van je bord terwijl je precisie behoudt.

CI-validatie voorkomt dat dingen uit elkaar lopen

Dit is de killer feature voor teams. Je domeinmodel wordt een volwaardig onderdeel van je ontwikkelworkflow. Elke PR die het domein wijzigt, wordt automatisch gevalideerd. Als iemand de YAML bijwerkt maar vergeet de documentatie te regenereren, pikt CI dat op.

Het model blijft dicht bij de code

Wanneer je domeinmodel in dezelfde repository leeft als je code, blijft het relevant. Het wordt beoordeeld in pull requests. Het wordt bijgewerkt wanneer features veranderen. Het verandert niet in verouderde documentatie in een ander systeem dat niemand zich herinnert te checken.

Aan de slag

Modelith is ontworpen om toegankelijk te zijn. Je hoeft niet meteen het hele schema te begrijpen. Begin klein:

• Installeer de Claude Code-plugin
• Beschrijf een paar kernconcepten uit je domein
• Laat de AI de YAML schetsen
• Draai modelith lint om te zien wat ontbreekt
• Itereer

Het project bevat uitgewerkte voorbeelden (hun parkeergarage-voorbeeld is een goed startpunt) die je door het bouwen van een echt model van scratch leiden.

Het Grotere Plaatje

Modelith vertegenwoordigt een bredere trend in AI-ondersteunde ontwikkeling: natuurlijke taal gebruiken als interfacelaag, terwijl je machine-leesbare artefacten eronder houdt. Je schrijft wat je bedoelt; de tooling zorgt voor consistentie en validatie.

Voor teams die complexe systemen bouwen — vooral in domeinen waar de terminologie ertoe doet (fintech, zorg, logistiek, alles met significante bedrijfsregels) — kan deze aanpak transformerend zijn. Een gedeeld, gevalideerd, levend domeinmodel betekent minder misverstanden, snellere onboarding en beter ontworpen systemen.

De tool is nog in ontwikkeling, maar het kernidee is solide. Je domeinmodel zou geen bijzaak of een relikwie van de projectkickoff moeten zijn. Het zou een levend document moeten zijn dat meebeweegt met je code, geschreven door conversatie, en automatisch gevalideerd.

Als je hebt gestruggled om domeinmodellen relevant te houden in je projecten, is Modelith het verkennen waard. Soms is de beste tooling niet de krachtigste — het is degene die het juiste gedrag de weg van de minste weerstand maakt.

Bekijk modelith.sh om te beginnen.