Parlare con il Tuo Codice: Come Modelith Dà Vita ai Domain Model

Siamo onesti — la maggior parte dei progetti inizia con le migliori intenzioni. Qualcuno disegna il domain model su una lavagna bianca, tutti annuiscono, e poi... muore silenziosamente in una pagina Confluence che nessuno aggiorna.

Il problema non è il concetto di domain modeling in sé. È che i domain model tradizionali sono tipicamente:

• Scritti una volta e dimenticati
• Mantenuti separatamente dal codice
• Leggibili solo con strumenti specifici
• Difficili da validare in modo automatico

Modelith prende un'altra strada. Invece di trattare il tuo domain model come un deliverable da produrre e archiviare, lo considera un artefatto vivo che convive con il tuo codice, che viene creato attraverso conversazioni e validato automaticamente in CI.

Cos'è Esattamente un Domain Model?

Prima di andare avanti, mettiamoci d'accordo. Un domain model è la mappa concettuale del tuo sistema — i nomi (entità), le loro relazioni e le regole che le governano. Non è uno schema di database né una specifica API. È l'espressione canonica, in linguaggio naturale, di cosa sia il tuo sistema.

Pensalo come il vocabolario condiviso da tutto il team. Quando tutti leggono dallo stesso modello, le conversazioni diventano più precise, l'onboarding è più veloce e aggiungere nuovi servizi o funzionalità non richiede più scavi archeologici nel codice legacy.

Il Workflow di Modelith: Descrivi, Genera, Valida, Renderizza

Qui le cose si fanno interessanti. Con Modelith non scrivi YAML direttamente. Non pensi nemmeno allo YAML. Descrivi i tuoi concetti di dominio in linguaggio naturale a un agente AI (in particolare, una skill di Claude Code), e l'agente genera lo YAML sottostante per te.

Il flusso funziona più o meno così:

1. Descrivi — Parli del tuo dominio in inglese semplice. "Abbiamo clienti che possono effettuare ordini, e gli ordini contengono più prodotti, ma i clienti possono avere al massimo tre ordini attivi contemporaneamente."

2. Genera — Il plugin di Claude Code traduce la tua descrizione in un file modelith.yaml, validando man mano.

3. Valida — Esegui modelith lint per verificare completezza e consistenza. Questo diventa il tuo gate CI.

4. Renderizza — Esegui modelith render per generare Markdown con diagrammi Mermaid. Fai commit di questo insieme allo YAML.

Il Markdown renderizzato è leggibile da umani senza bisogno di strumenti. Lo YAML è la fonte di verità leggibile dalla macchina. E CI garantisce che non divergano mai — pensalo come un controllo del codice generato, ma per il tuo domain model.

Perché Questo Approccio Funziona

Il linguaggio naturale abbassa le barriere

Non tutti nel team si trovano a loro agio leggendo JSON Schema o diagrammi UML. Ma tutti possono leggere l'inglese semplice. Rendendo il linguaggio naturale il punto d'ingresso, Modelith democratizza il domain modeling. Il tuo product manager può contribuire. Il tuo QA engineer può rivederlo. Il tuo dev junior può davvero capire il quadro generale.

L'AI gestisce le parti noiose

Scrivere YAML a mano è soggetto a errori e, onestamente, tedioso. Lasciare che un agente AI curi la traduzione dalla tua descrizione a YAML valido significa toglierti questo peso cognitivo mantenendo la precisione.

La validazione CI previene la deriva

Questa è la funzionalità chiave per i team. Il tuo domain model diventa un cittadino di prima classe nel tuo workflow di sviluppo. Ogni PR che modifica il dominio viene validato automaticamente. Se qualcuno aggiorna lo YAML ma dimentica di rigenerare i docs, CI lo coglie.

Il modello resta vicino al codice

Quando il tuo domain model vive nello stesso repository del tuo codice, resta rilevante. Viene rivisto nelle pull request. Viene aggiornato quando le funzionalità cambiano. Non diventa documentazione obsoleta in qualche altro sistema che nessuno ricorda di controllare.

Come Iniziare

Modelith è pensato per essere accessibile. Non devi capire l'intero schema fin dall'inizio. Inizia in piccolo:

• Installa il plugin di Claude Code
• Descrivi qualche concetto chiave del tuo dominio
• Lascia che l'AI generi lo YAML
• Esegui modelith lint per vedere cosa manca
• Itera

Il progetto include esempi pratici (il loro esempio del parcheggio è un buon punto di partenza) che ti guidano nella costruzione di un modello reale da zero.

Il Quadro Più Ampio

Modelith rappresenta una tendenza più ampia nello sviluppo assistito da AI: usare il linguaggio naturale come livello di interfaccia mentre si mantengono artefatti leggibili dalla macchina sotto il cofano. Scrivi quello che pensi; gli strumenti si occupano di consistenza e validazione.

Per i team che costruiscono sistemi complessi — specialmente in domini dove il vocabolario conta (fintech, healthcare, logistica, qualsiasi cosa con significative regole di business) — questo approccio potrebbe essere trasformativo. Un domain model condiviso, validato e vivo significa meno malintesi, onboarding più rapido e sistemi meglio progettati.

Lo strumento è ancora in evoluzione, ma l'idea di base è solida. Il tuo domain model non dovrebbe essere un ripensamento o un reperto del kickoff del progetto. Dovrebbe essere un documento vivo che evolve con il tuo codice, creato attraverso conversazioni e validato automaticamente.

Se hai faticato a mantenere rilevanti i domain model nei tuoi progetti, Modelith merita di essere esplorato. A volte i migliori strumenti non sono i più potenti — sono quelli che rendono il comportamento giusto la via più facile.

Scopri modelith.sh per iniziare.