Living Documentation, Spec-Driven Development e DDD
Nei team di sviluppo la documentazione è spesso percepita come un male necessario: qualcosa da produrre a valle del lavoro, sotto pressione, e proprio per questo destinata rapidamente a diventare obsoleta. Diagrammi che descrivono sistemi che non esistono più, documenti che nessuno legge, decisioni perse nella memoria dei singoli.
Negli ultimi anni, però, l’adozione sempre più diffusa di agenti AI come assistenti allo sviluppo sta riportando la documentazione al centro del processo. Approcci come lo Spec-Driven Development richiedono specifiche esplicite, coerenti e mantenute nel tempo. Per consentire agli agenti di lavorare efficacemente, il contesto deve essere reso esplicito: non basta più “sapere” come funziona il sistema, è necessario poterlo leggere, verificare e aggiornare.
Questo scenario rende evidente che la documentazione non può più essere un artefatto secondario. Deve diventare una parte attiva del progetto, al pari del codice. È in questo spazio che si colloca il confronto tra Living Documentation e Spec-Driven Development.
Cosa significa Living Documentation?
Il problema della documentazione accompagna l’informatica fin dalle sue origini, ma una delle trattazioni più mature del tema si trova nel libro “Living Documentation – Continuous Knowledge Sharing by Design” di Cyrille Martraire.
Il testo non si presenta come un manuale prescrittivo, bensì come un percorso concettuale. Il punto di partenza è un’osservazione semplice e radicale: la documentazione fallisce perché è separata dal sistema che dovrebbe descrivere. Viene scritta una volta, raramente aggiornata, e perde rapidamente credibilità. Quando questo accade, il team smette di leggerla e, di conseguenza, di mantenerla.
La Living Documentation nasce come risposta a questo fallimento. Secondo Martraire, è documentazione che deriva direttamente dal sistema e ne condivide il ciclo di vita. Le sue caratteristiche fondamentali sono:
- è estratta da codice, test e modelli;
- si può verificare automaticamente;
- leggibile dagli esseri umani;
- è parte integrante del flusso di sviluppo, non un’attività separata.
Non si tratta quindi di uno strumento, ma di un approccio di design e di lavoro. Chi ha esperienza con pratiche come BDD o con il Domain-Driven Design riconoscerà molte affinità.
Le fonti della Living Documentation
Martraire individua diverse “fonti di verità” da cui la documentazione può emergere.
La prima è il codice. Un codice ben scritto, con nomi espressivi, tipi chiari e una struttura coerente, racconta già una storia. In questo senso, scrivere buon codice significa già documentare.
Seguono i test come esempi eseguibili. In particolare, i test di dominio o in stile BDD diventano narrazioni verificabili del comportamento del sistema: spiegano cosa fa il sistema e perché lo fa.
Infine, il dominio come conoscenza centrale. Il modello di dominio, espresso attraverso l’Ubiquitous Language, è forse la forma più preziosa di documentazione: cattura regole di business, concetti chiave e decisioni condivise tra business e tecnologia.
In sintesi, la Living Documentation non descrive il sistema dall’esterno, ma ne è una conseguenza naturale. Il suo scopo è:
- spiegare perché il sistema è fatto in un certo modo;
- rendere visibili le decisioni di design;
- preservare la conoscenza nel tempo.
Che si intende per Spec-Driven Development?
Per molti anni, nello sviluppo software, il codice è stato l’unica vera fonte di verità. Le specifiche esistevano, ma erano subordinate: documenti di requisiti, diagrammi e design doc che avevano un destino comune, quello di diventare obsoleti non appena il codice iniziava a evolvere.
In questo paradigma, per capire cosa facesse un sistema bisognava leggerne il codice. Per validarlo, bisognava eseguirlo. Per discuterlo, bisognava interpretarlo. Il codice era contemporaneamente implementazione, documentazione e verità.
Questo approccio ha un limite strutturale: rende difficile avere implementazioni alternative o parallele e concentra tutta la conoscenza in un artefatto che non è pensato per essere discusso a livello concettuale.
Lo Spec-Driven Development ribalta questa struttura. In un contesto Spec-Driven, le specifiche non servono al codice: è il codice che serve alle specifiche.
Il Product Requirements Document (PRD) non è più una guida informale, ma una fonte formale da cui l’implementazione viene generata o verificata. I documenti tecnici non informano la codifica: la definiscono. Le specifiche non descrivono ciò che il sistema dovrebbe fare; stabiliscono ciò che deve fare.
Non è un miglioramento incrementale, ma un cambio di paradigma: la verità non risiede più nel codice, bensì nel contratto che il codice è obbligato a rispettare.
Il flusso Spec-Driven
Il processo inizia spesso da un’idea vaga. Attraverso un dialogo iterativo, anche supportato da agenti AI, questa idea viene raffinata fino a diventare un PRD coerente, completo di criteri di accettazione e casi limite.
Requisiti e progettazione smettono di essere fasi isolate e diventano attività continue. Le specifiche vengono versionate, discusse, ramificate e integrate come qualsiasi altro artefatto di progetto.
Da queste specifiche emergono piani di implementazione che collegano requisiti a decisioni tecniche. Ogni scelta architetturale è tracciabile, ogni decisione ha una motivazione esplicita. La generazione del codice può iniziare anche con specifiche parziali, in modo esplorativo, producendo modelli, API e test direttamente a partire dalle definizioni formali.
Il feedback non si ferma allo sviluppo: metriche di produzione, incidenti e problemi di performance diventano input che aggiornano le specifiche, alimentando un ciclo di evoluzione continua.
Living Documentation e Spec-Driven Development a confronto
Per comprendere davvero la differenza tra Living Documentation e Spec-Driven Development è necessario guardare oltre strumenti e pratiche operative, concentrandosi su alcuni assi fondamentali: intento, sequenza temporale, ruolo delle specifiche e rapporto con il dominio.
Intento: conoscenza vs controllo
La Living Documentation nasce per condividere e preservare la conoscenza reale del sistema. Riduce la distanza tra ciò che il sistema è e ciò che le persone comprendono, rendendo visibili decisioni, regole e modelli.
Lo Spec-Driven Development ha invece un intento normativo: guidare lo sviluppo attraverso specifiche formali che fungono da contratto.
Sequenza temporale: emergenza vs prescrizione
La Living Documentation emerge durante e dopo lo sviluppo ed è evolutiva per natura. Il suo allineamento è garantito dall’automazione.
Lo Spec-Driven Development opera prima dell’implementazione. Le specifiche precedono il sistema e ne vincolano l’evoluzione, richiedendo disciplina per rimanere coerenti.
Il ruolo delle specifiche
Nella Living Documentation le specifiche sono implicite, espresse tramite codice, test e modelli. Raccontano ciò che esiste davvero.
Nel paradigma Spec-Driven le specifiche sono esplicite, formali e versionate separatamente. Definiscono ciò che il sistema deve diventare.
Il ruolo dei test
Nella Living Documentation i test sono narrazione ed esempi eseguibili, dove la leggibilità ha la precedenza sulla completezza.
Nello Spec-Driven Development i test sono strumenti di verifica della conformità, guardiani del contratto.
Relazione con Domain-Driven Design
La Living Documentation si integra in modo naturale con il DDD: il modello di dominio è centrale, l’Ubiquitous Language è fondamentale e i Bounded Context diventano unità di documentazione.
Lo Spec-Driven Development è invece più situazionale. Funziona molto bene ai confini del sistema – API, integrazioni, contesti regolamentati – ma può risultare rigido nei domini complessi e in fase di esplorazione.
Una lettura matura
Living Documentation e Spec-Driven Development non sono in contraddizione.
Nelle architetture moderne, una combinazione efficace prevede spesso:
- Spec-Driven Development ai confini del sistema (API, integrazioni, eventi);
- Living Documentation all’interno dei Bounded Context, nel modello di dominio e nelle decisioni.
In altre parole:
Le specifiche proteggono il sistema.
La Living Documentation protegge la conoscenza.