Idea principale

Attorno a un prodotto software gravita una famiglia di artefatti: la specifica, il mockup Figma, il changelog, la documentazione di supporto, la documentazione commerciale. Nessuno di essi dice che cosa fa il prodotto oggi. Dicono che cosa si voleva che facesse, o che cosa faceva nel momento in cui qualcuno li ha scritti.

Il codice, invece, non può sbagliarsi sullo stato del prodotto: è quello stato. Un comportamento presente nel repository è un comportamento del prodotto, che sia stato specificato o no; un comportamento scritto in una specifica e assente dal repository non esiste per nessuno.

Questo non fa del codice un buon supporto di lettura, né un sostituto degli altri artefatti. Stabilisce soltanto una gerarchia di affidabilità: se il repository e un documento non concordano, è il documento ad avere torto.

La stessa classifica vale per gli artefatti di coordinamento: un ticket e una specifica si desincronizzano l'uno dall'altra e dal prodotto fin dalla realizzazione, e l'unica realtà duratura resta ciò che viene consegnato — il codice, il comportamento osservabile e la documentazione mantenuta a partire da essi.

Contributo di «Il backlog non è una discarica: è uno strumento d'azione» (2026-06-03).

Fare fede sullo stato del prodotto non equivale a descriverlo. Il codice stabilisce come funziona il prodotto — i campi, i valori possibili, le elaborazioni — e lascia fuori ciò che lo rende utilizzabile: la regola enunciata in una frase, quando il suo controllo è sparso in cinque file; i casi particolari di un oggetto; le parole usate dagli utenti; la portata di una nozione quando due applicazioni danno un significato diverso allo stesso termine. Queste quattro informazioni, del resto, non si trovano nello stesso posto: si distribuiscono fra il cuore del codice, la base di dati, le schermate e le traduzioni. La gerarchia di affidabilità resta vera; non dispensa dallo scrivere il significato sopra.

Contributo di «Ho scritto l'ontologia di un prodotto. Tre volte ho creduto di aver finito.» (2026-08-11).

La gerarchia si verifica anche nel caso in cui viene portata all'estremo. Su uno strumento interno costruito senza specifica preliminare — qualcuno si butta, costruisce, mostra, riceve richieste, aggiusta —, nessun documento ha mai descritto l'intenzione, eppure il prodotto funziona. Il contrario non esiste: non c'è prodotto che funzioni senza codice. La specifica non sparisce per questo da tutti i contesti, ma smette di poter pretendere di essere in modo duraturo la verità del prodotto.

Contributo di «Quattro giorni di vibe coding…» (2026-07-28).

Perché è importante

Questa gerarchia viene enunciata di rado, eppure è applicata di continuo: uno sviluppatore che deve chiarire un comportamento ambiguo va a leggere il codice, non la specifica. Dirlo esplicitamente cambia ciò che ci si aspetta dagli altri artefatti: diventano viste, datate, e non riferimenti.

Fornisce anche un criterio per risolvere un conflitto tra due artefatti senza riunire gli autori: non si cerca chi ha ragione, si guarda il repository.

Sfumature e limiti

Il codice dice che cosa fa il prodotto, mai perché. L'intenzione, la scelta, il vincolo commerciale che hanno portato a quel comportamento non vi si leggono — e quella parte resta nei documenti e negli scambi di progetto.

La regola vale per il comportamento consegnato, non per quello voluto: un bug sta nel codice, eppure fa parte di ciò che andrà cambiato.

Domande aperte

• Chi si accorge che un'intenzione di prodotto è scomparsa, quando il comportamento che ha prodotto continua a girare senza di essa?