Registri delle Decisioni per lo Sviluppo Software Guidato dall'IA

I registri delle decisioni costituiscono lo strato di memoria mancante nello sviluppo software assistito dall’intelligenza artificiale. Essi catturano non solo ciò che è stato costruito, ma anche il perché — e questa distinzione diventa critica quando gli strumenti di IA scrivono il vostro codice.

I registri delle decisioni sono lo strato di memoria mancante

La programmazione guidata dall’IA cambia l’economia dello sviluppo software rendendo il codice più economico da generare, più facile da refattorizzare e più veloce da scartare. Questo è utile. È anche pericoloso, perché quando il codice diventa più facile da produrre, la risorsa scarsa non è più la digitazione — la risorsa scarsa è il giudizio.

Perché il team ha scelto PostgreSQL invece di DynamoDB? Perché il prodotto richiede una revisione umana prima di inviare email generate dall’IA? Perché l’interfaccia mostra suggerimenti in un pannello laterale invece di applicarli direttamente? Perché un approccio più semplice è stato rifiutato sei mesi fa? Il codice può mostrare cosa esiste, ma raramente spiega perché esiste.

I registri delle decisioni risolvono questo problema fornendo un documento breve, controllato per versione, che cattura una scelta importante, il contesto dietro di essa, le alternative considerate e le conseguenze che il team ha accettato. In una codebase assistita dall’IA, questi registri diventano più della semplice documentazione — diventano memoria di progetto durevole che sia gli umani che gli agenti di coding IA possono leggere prima di apportare modifiche future. La regola operativa pratica è semplice: mantenere i registri delle decisioni come file Markdown nel repository, revisionarli come codice e permettere agli strumenti IA futuri di leggerli prima di proporre o implementare modifiche.

Cosa sono i registri delle decisioni?

Un registro delle decisioni è una registrazione scritta di una decisione significativa, strutturata per rispondere a quattro domande di base: cosa abbiamo deciso, perché l’abbiamo deciso, quali alternative abbiamo considerato e quali conseguenze abbiamo accettato? La forma più comune è il Registro delle Decisioni Architetturali (Architecture Decision Record), abbreviato in ADR. Gli ADR sono ampiamente utilizzati per documentare le decisioni tecniche e lo stesso modello può essere esteso oltre l’architettura al lavoro sul prodotto e sul design.

Per la programmazione guidata dall’IA, tre tipi sono particolarmente utili:

Insieme, ADR, PDR e DDR descrivono non solo la struttura del sistema, ma anche l’intenzione del prodotto e il ragionamento dietro l’esperienza utente. Questa combinazione è importante perché gli agenti IA possono leggere il codice, ma il codice da solo non contiene abbastanza contesto per prendere buone decisioni. I registri delle decisioni forniscono ai sistemi IA una fonte di intenzione di progetto revisionata, durevole e approvata dall’uomo.

Registri delle Decisioni Architetturali

I Registri delle Decisioni Architetturali (Architecture Decision Records) catturano decisioni tecniche e strutturali. Utilizzate un ADR quando una decisione influenza la forma del sistema — i suoi confini, le dipendenze, il modello operativo o la manutenibilità a lungo termine.

Gli esempi di decisioni che vale la pena registrare come ADR includono:

• Scegliere PostgreSQL come database principale
• Utilizzare un’architettura guidata dagli eventi per l’elaborazione in background
• Mantenere l’applicazione come monolite modulare
• Introdurre una coda di messaggi
• Scegliere REST invece di GraphQL
• Utilizzare il rendering lato server per l’applicazione web
• Richiedere che tutti i lavori in background siano idempotenti
• Adottare un modello specifico di autenticazione e autorizzazione

Un ADR non è un documento architetturale completo — è intenzionalmente piccolo, registrando una decisione importante in un momento specifico. Un buon ADR previene l’oblio architetturale: senza di esso, i contributori futuri potrebbero riscoprire gli stessi compromessi, riaprire vecchie discussioni o annullare accidentalmente vincoli importanti.

Nella programmazione guidata dall’IA, gli ADR hanno ancora più peso. Gli strumenti IA sono spesso abili nell’ottimizzazione locale e possono proporre una modifica tecnicamente plausibile che viola un vincolo architetturale più ampio. Un ADR fornisce all’IA un confine chiaro: “Questo è come questo sistema dovrebbe essere strutturato.”

Registri delle Decisioni di Prodotto

I Registri delle Decisioni di Prodotto (Product Decision Records) catturano il comportamento del prodotto, l’ambito e l’intenzione rivolta all’utente. Questo è meno comune rispetto agli ADR, ma spesso è altrettanto prezioso — le decisioni di prodotto sono frequentemente sparse tra ticket, strumenti di pianificazione, thread di chat, note delle riunioni e memorie delle persone, rendendole facili da dimenticare per gli umani e quasi impossibili da inferire in modo affidabile per gli strumenti IA.

Utilizzate un PDR quando una decisione influenza ciò che il prodotto fa, a chi serve, cosa è intenzionalmente fuori ambito o come dovrebbe comportarsi una funzionalità visibile all’utente. Gli esempi includono:

• I messaggi generati dall’IA devono rimanere bozze fino a quando non vengono revisionati da un umano
• Gli utenti del piano gratuito possono creare fino a tre progetti
• Gli spazi di lavoro eliminati sono recuperabili per 30 giorni
• La fatturazione per team è fuori ambito per la versione 1
• Gli utenti possono esportare i loro dati senza contattare il supporto
• I riassunti dell’IA con bassa fiducia mostrano un avviso invece di essere nascosti

Un PDR è particolarmente utile quando una scelta di prodotto sembra arbitrata dal codice. Il codice potrebbe contenere un limite di tre progetti per gli utenti gratuiti e, senza un PDR, uno strumento IA potrebbe trattare quel numero come una costante magica e suggerirne la modifica. Con un PDR, l’IA può vedere che il limite è legato alla strategia di pricing, al costo di onboarding o al carico di supporto — e che modificarlo richiede una decisione di prodotto deliberata, non una rapida modifica.

Registri delle Decisioni di Design

I Registri delle Decisioni di Design (Design Decision Records) catturano decisioni relative all’esperienza utente, all’interazione, al design visivo e al design dei contenuti. Utilizzate un DDR quando una decisione influenza come gli utenti interagiscono con il prodotto, come viene presentata l’informazione o come un principio di design dovrebbe essere applicato nei lavori futuri.

Gli esempi di decisioni di design che vale la pena registrare includono:

• Utilizzare la validazione inline invece della validazione solo al momento dell’invio
• Mettere i suggerimenti dell’IA in un pannello laterale invece che direttamente nell’editor
• Utilizzare la rivelazione progressiva per le impostazioni avanzate
• Richiedere conferma prima delle azioni distruttive
• Usare “Bozza” e “Pubblicato” invece di “Inattivo” e “Attivo”
• Mantenere le azioni primarie visibili sugli schermi mobili

L’intenzione di design è facile da perdere durante l’implementazione. Uno sviluppatore potrebbe semplificare un flusso, o un agente IA potrebbe generare un componente che tecnicamente funziona ma rompe il modello di interazione previsto. Ad esempio, un DDR potrebbe registrare: “Mostriamo i suggerimenti di scrittura dell’IA accanto al documento, non al suo interno, perché gli utenti devono confrontare il testo generato con la propria bozza prima di accettare le modifiche.” Questo registro fornisce ai contributori futuri un principio da preservare, non solo un layout da copiare.

Perché i registri delle decisioni sono più importanti con l’IA

Gli strumenti di coding IA sono potenti, ma sono spesso senza stato o solo parzialmente consapevoli della storia del progetto. Possono ispezionare file, inferire pattern e generare modifiche — ma non sanno automaticamente quali decisioni sono intenzionali, quali sono accidentali e quali sono già state discusse e risolte. Questo crea diversi rischi distinti.

L’IA potrebbe riaprire dibattiti già chiusi

Se il team ha già deciso di utilizzare un monolite modulare, un agente IA potrebbe ancora proporre di estrarre un servizio perché sembra pulito in isolamento. Senza un ADR, l’IA non ha un modo durevole per sapere che il team ha già considerato e rifiutato quella strada, e il risultato è uno sforzo sprecato o una regressione sottile nella coerenza del sistema.

L’IA potrebbe ottimizzare localmente e danneggiare globalmente

Un refactoring generato potrebbe rendere un file più pulito violando i confini del sistema. Una modifica UI potrebbe ridurre la complessità del componente indebolendo l’esperienza utente prevista. Una modifica al prodotto potrebbe semplificare l’implementazione rompendo le assunzioni di pricing o conformità. I registri delle decisioni forniscono all’IA un quadro di riferimento più ampio prima che agisca su segnali a ambito ristretto.

L’IA potrebbe preservare il codice ma perdere l’intenzione

Un modello può seguire i pattern esistenti nella codebase, ma i pattern non sono la stessa cosa dei principi. A volte il codice esistente è un compromesso. A volte è transitorio. A volte esiste a causa di un vincolo esterno non visibile nel file. I registri delle decisioni spiegano la differenza tra “questo è come funziona” e “questo è perché è stato costruito in questo modo”.

L’IA potrebbe generare una razionale plausibile ma errata

L’IA può redigere registri delle decisioni, ma può anche inventare spiegazioni che suonano sicure ma che non corrispondono alla decisione reale. Questo è il motivo per cui la revisione umana è innegoziable: l’IA può generare la prima bozza di un registro, ma un umano deve verificare che descriva accuratamente la decisione effettiva, le alternative e le conseguenze prima che il registro venga unito (merged).

I registri delle decisioni come parte di una metodologia più ampia

I registri delle decisioni non sono solo documentazione — fanno parte di un modo più ampio di lavorare che si trova all’intersezione della governance architetturale leggera, della documentazione come codice, flussi di lavoro di gestione della conoscenza potenziati dall’IA, della scoperta del prodotto, della razionale di design, della governance dell’IA e della revisione del codice. Un modo utile per descrivere il processo più ampio è lo Sviluppo Orientato alle Decisioni (Decision-Oriented Development).

La maggior parte dei flussi di lavoro di programmazione guidata dall’IA si concentra strettamente sul ciclo generare-revisionare-commit:

Questo ciclo è troppo sottile per il lavoro serio sui sistemi. Un flusso di lavoro più forte tratta il repository come un archivio sia di codice che di intenzione — i diagrammi qui utilizzano Mermaid, un formato leggero che funziona bene anche all’interno dei registri delle decisioni Markdown:

Questo processo trasforma il repository in qualcosa di più di un archivio di codice. Diventa la fonte di verità per l’implementazione, l’intenzione e il ragionamento — un artefatto durevole che accumula valore con ogni decisione presa.

I registri delle decisioni e la documentazione come codice

I registri delle decisioni funzionano meglio quando seguono i principi della documentazione come codice, il che significa che dovrebbero essere archiviati nello stesso repository del codice, scritti in Markdown semplice, revisionati nelle pull request, versionati con Git, collegati a issue e pull request correlate e ricercabili sia dagli umani che dagli strumenti IA. Questo è molto più affidabile rispetto a conservare decisioni importanti in chat, pagine wiki, presentazioni o note delle riunioni — quegli strumenti possono ancora essere utili per la discussione, ma la decisione accettata dovrebbe sempre vivere vicino al codice. Mantenere Specifiche, Test e Codice in Sincronia nello Sviluppo IA estende questa stessa abitudine di “collegarlo al registro” in un modello di tracciabilità completo che lega gli ID delle decisioni dei requisiti e del design ai test e alle pull request.

Una struttura di repository ben organizzata per i registri delle decisioni potrebbe apparire così:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

Per progetti più piccoli, una struttura più piatta funziona ugualmente bene. L’organizzazione esatta delle cartelle è meno importante della coerenza — i registri devono essere facili da trovare, facili da revisionare e facili per gli strumenti IA da caricare come contesto prima di agire sulla codebase. Per i team Go, questa struttura docs/decisions/ si adatta naturalmente accanto al layout cmd/, internal/ e api/ descritto in Struttura del Progetto Go: Pratiche & Pattern, che raccomanda docs/ come casa per le decisioni architetturali e i riferimenti API.

Un template pratico per i registri delle decisioni

Un template utile per i registri delle decisioni dovrebbe essere abbastanza breve da essere effettivamente utilizzato. Ecco un template Markdown pratico che include una sezione di guida per l’IA opzionale ma preziosa:

# Decisione: Titolo breve

Stato: Proposta | Accettata | Sostituita | Deprecata
Data: AAAA-MM-GG
Tipo: Architettura | Prodotto | Design
Responsabili: Team o nomi

## Contesto

Descrivere il problema, i vincoli, gli obiettivi, le esigenze degli utenti, i fatti tecnici
e i fattori aziendali che hanno portato a questa decisione.

## Decisione

Enunciare la decisione chiaramente.

## Alternative considerate

### Opzione 1

Pro:
- ...

Contro:
- ...

## Conseguenze

Descrivere cosa diventa più facile, cosa diventa più difficile e quali rischi
o lavori di follow-up questo crea.

## Guida per l'IA

Quando un assistente IA lavora in questa area, dovrebbe:
- Preservare ...
- Evitare ...
- Preferire ...
- Chiedere revisione quando ...

## Link

- Issue correlate:
- Pull request correlate:
- File correlati:
- Sostituisce:
- Sostituita da:

La sezione “Guida per l’IA” è opzionale, ma per la programmazione guidata dall’IA è estremamente preziosa — trasforma il registro delle decisioni in un’istruzione durevole per i futuri agenti che lavorano nella stessa area della codebase.

Cosa appartiene a un registro delle decisioni?

Non ogni scelta merita un registro e, se ogni piccolo dettaglio implementativo diventa un registro delle decisioni, il processo collassa nel rumore. Create un registro delle decisioni quando una scelta è significativa e probabilmente importante in futuro.

I buoni candidati sono decisioni che:

• Influenzano più parti del sistema
• Codificano una promessa di prodotto
• Risolvono un dibattito reale
• Introducono un compromesso a lungo termine
• Dipendono da vincoli aziendali, di conformità o operativi
• Sarebbero costosi da riscoprire in seguito
• Gli strumenti IA futuri potrebbero plausibilmente gestire male
• I contributori futuri potrebbero essere tentati di invertire casualmente

I cattivi candidati includono piccole scelte di refactoring, bug fix ovvi, esperimenti temporanei, decisioni di denominazione locale e dettagli implementativi senza conseguenze durature. Una buona regola empirica è semplice: se invertire la decisione richiedesse una discussione, registrate la decisione.

Valori di stato e ciclo di vita

I registri delle decisioni dovrebbero avere un ciclo di vita per segnalare la loro validità attuale. I valori di stato più semplici sono sufficienti.

Proposta — La decisione è in considerazione ma non ancora accettata. Utilizzate questo quando il team vuole discutere una decisione in una pull request prima di impegnarsi.

Accettata — La decisione è attiva e dovrebbe guidare il lavoro futuro. La maggior parte dei registri delle decisioni utili passerà la maggior parte della loro vita in questo stato.

Sostituita — La decisione è stata sostituita da un registro più recente. Non eliminate i vecchi registri; conservateli per la storia e collegate alla decisione più recente in modo che l’evoluzione del pensiero rimanga visibile.

Deprecata — La decisione non è più raccomandata ma può ancora descrivere parti esistenti del sistema. Questo è particolarmente utile durante le migrazioni, quando vecchi pattern esistono nella codebase accanto a approcci più nuovi.

Il principio importante è che i registri delle decisioni dovrebbero essere amichevoli alle aggiunte. Quando il team cambia direzione, create un nuovo registro e collegate quello vecchio invece di riscrivere la storia per far sembrare il passato più pulito.

Come l’IA dovrebbe generare registri delle decisioni

L’IA può aiutare a creare registri delle decisioni e questo è uno degli usi migliori dell’IA nello sviluppo software — è veloce nel redigere documenti strutturati dal contesto. Dopo una discussione, una revisione architetturale o una pull request, potete chiedere a un assistente IA di redigere un registro:

Redigi un Registro delle Decisioni Architetturali per la decisione in questa pull request.
Includi contesto, alternative, conseguenze e guida per l'IA.
Salvalo come Markdown sotto docs/decisions/architecture.

Per il lavoro di prodotto:

Redigi un Registro delle Decisioni di Prodotto spiegando perché i messaggi generati dall'IA
devono rimanere bozze fino a quando non vengono revisionati dall'utente.
Includi impatto utente, comportamento fuori ambito, compromessi e guida per l'IA.

Il registro generato dall’IA non dovrebbe essere fidato automaticamente, tuttavia. La revisione umana dovrebbe verificare che il contesto sia accurato, che l’IA non abbia inventato la razionale, che le alternative elencate siano reali, che le conseguenze siano oneste e che la guida per l’IA corrisponda all’intenzione effettiva del team. L’IA è un assistente di bozze — non è il proprietario della decisione.

Come l’IA dovrebbe leggere i registri delle decisioni

L’altra metà della pratica è istruire l’IA a leggere i registri prima di agire. Prima di chiedere a un assistente IA di implementare una modifica, includete un’istruzione come questa:

Prima di modificare questa funzionalità, leggi docs/decisions.
Identifica qualsiasi Registro delle Decisioni Architetturali, di Prodotto o di Design che si applichi.
Segui le decisioni accettate. Se la tua modifica proposta è in conflitto con un registro
delle decisioni, spiega il conflitto prima di modificare il codice.

Per compiti più grandi, rinforza il ruolo dei registri come memoria del progetto:

Utilizza i registri delle decisioni come memoria del progetto.
Non invertire le decisioni accettate senza proporre una nuova decisione sostitutiva.
Quando generi codice, spiega quali registri delle decisioni hanno influenzato l'implementazione.

Questo cambia il ruolo dell’IA da “predire codice plausibile” a “operare all’interno di un sistema documentato di vincoli” — un miglioramento significativo nella affidabilità per progetti complessi o a lunga vita.

I registri delle decisioni nelle pull request

I registri delle decisioni dovrebbero far parte della revisione normale delle pull request piuttosto che di un processo separato. Una semplice voce nella checklist della PR rende l’abitudine visibile:

## Checklist del registro delle decisioni

- [ ] Questa PR non introduce una decisione significativa di architettura, prodotto o design.
- [ ] Questa PR introduce una decisione significativa e include un nuovo registro delle decisioni.
- [ ] Questa PR cambia una decisione precedente e include un registro sostitutivo.
- [ ] I registri delle decisioni esistenti rilevanti sono stati considerati.
- [ ] Il codice generato dall'IA segue i registri delle decisioni accettati.
- [ ] I registri delle decisioni generati dall'IA sono stati revisionati da un umano.

Questa checklist è semplice, ma cambia il comportamento ricordando al team che il codice non è l’unico artefatto importante in una pull request. Rende anche naturale catturare quando una modifica generata dall’IA viola silenziosamente una decisione precedente.

I registri delle decisioni e la governance architetturale

La governance architetturale tradizionale spesso fallisce perché è troppo pesante, troppo lenta o troppo scollegata dall’implementazione — consigli di approvazione centrali, documenti iniziali di grandi dimensioni e processi di gatekeeping che bloccano invece di guidare. I registri delle decisioni offrono un’alternativa più leggera che si integra direttamente nel flusso di lavoro di sviluppo.

Non richiedono un consiglio architetturale centrale per ogni cambiamento, né bloccano i team dall’apprendere e adattarsi. Invece, creano una scia di decisioni che possono essere revisionate, referenziate e costruite nel tempo. Questo supporta l’architettura evolutiva: l’architettura può cambiare, ma cambia con memoria piuttosto che nonostante essa. Il team può rivedere le vecchie decisioni senza dover riscoprire perché sono state prese, che è una forma di governance più sana e onesta:

• Registri piccoli invece di documenti giganteschi
• Revisione vicina al codice invece di teatro di approvazione separato
• Contesto storico invece di conoscenza tribale
• Compromessi espliciti invece di assunzioni nascoste

I registri delle decisioni e la gestione del prodotto

Il lavoro di prodotto ha anche bisogno di memoria decisionale e questa è un’area in cui il valore dei registri delle decisioni è spesso sottostimato. Un roadmap dice cosa potrebbe accadere. Un ticket dice cosa costruire dopo. Le analytics dicono cosa hanno fatto gli utenti. Nessuno di questi spiega completamente perché esiste un comportamento di prodotto.

I Registri delle Decisioni di Prodotto colmano questa lacuna e sono particolarmente utili per decisioni di pricing e packaging, modelli di permessi, limiti e quote, flussi di sicurezza e revisione dell’IA, scelte di onboarding, definizioni dei ruoli utente, regole di collaborazione, politiche di conservazione dei dati e confini dell’ambito delle funzionalità. Una volta implementate, le decisioni di prodotto diventano invisibili nel codice — in seguito, qualcuno vede solo il codice e chiede: “Perché funziona in questo modo?” Un PDR fornisce la risposta in una forma che sia gli umani che gli strumenti IA possono trovare e utilizzare.

I registri delle decisioni e i sistemi di design

I sistemi di design spesso documentano componenti, token e regole di utilizzo, ma raramente documentano perché il sistema funziona in quel modo. I Registri delle Decisioni di Design colmano questa lacuna. Una libreria di componenti potrebbe dire “usa il dialogo di conferma per le azioni distruttive”, mentre un DDR spiega la razionale: “Richiediamo la conferma per le azioni distruttive perché gli utenti spesso lavorano con dati di team condivisi e la cancellazione accidentale ha un alto costo di recupero.”

Quella razionale è importante oltre al componente specifico. Aiuta i designer futuri, gli sviluppatori e gli strumenti IA ad applicare il principio correttamente in nuove situazioni. Senza il DDR, un agente IA potrebbe generare un’interazione più veloce che salta la conferma perché appare più efficiente. Con il DDR, l’agente può riconoscere che preservare la proprietà di sicurezza è intenzionale e innegoziable.

Come i registri delle decisioni supportano lo sviluppo guidato dalle specifiche

Lo sviluppo guidato dalle specifiche (Spec-driven development) spiega cosa il sistema dovrebbe fare. I registri delle decisioni spiegano perché il team ha scelto quella direzione e la distinzione è significativa per il lavoro assistito dall’IA.

Una specifica di funzionalità potrebbe dire che le email generate dall’IA devono essere salvate come bozze. Un Registro delle Decisioni di Prodotto spiega perché l’invio automatico è stato rifiutato, quali rischi sono stati considerati e quali cambiamenti futuri richiederebbero una nuova decisione. Una specifica di design potrebbe descrivere un’interazione di pannello laterale, mentre il DDR corrispondente spiega perché le modifiche inline dell’IA sono state esplicitamente rifiutate e perché preservare il controllo dell’utente è stato pesato più fortemente rispetto alla velocità del flusso di lavoro. Una specifica architetturale potrebbe definire un confine di servizio e il suo ADR spiega perché il team ha scelto quel confine rispetto a un’alternativa più semplice o più distribuita.

La specifica guida l’implementazione. Il registro delle decisioni preserva il giudizio. Insieme, forniscono agli agenti di coding IA sia istruzioni che contesto — il “cosa” e il “perché” — che è ciò che rende la combinazione così efficace per sistemi complessi e a lunga vita. Quando adottate una toolchain guidata dalle specifiche, confrontate come ogni opzione esponga quel contesto; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows analizza portabilità, gate di revisione e ancoraggio al repository attraverso le principali configurazioni. Per il processo neutro agli strumenti in cinque fasi che questi strumenti implementano, vedere Flusso di Lavoro di Sviluppo Guidato dalle Specifiche dai Requisiti al Codice.

I registri delle decisioni non sono specifiche

I registri delle decisioni sono correlati alle specifiche, ma servono uno scopo diverso. Una specifica dice “il sistema farà X”, mentre un registro delle decisioni dice “abbiamo scelto X invece di Y a causa di questi vincoli e compromessi”. Quel “invece di Y” è la parte preziosa. Gli strumenti IA spesso generano soluzioni trovando un percorso plausibile verso il risultato richiesto, ma i registri delle decisioni dicono loro quali percorsi plausibili sono già stati esplorati, valutati e rifiutati — riducendo il turnover e migliorando la qualità del lavoro assistito dall’IA.

I registri delle decisioni non sono un sostituto dei test

I test verificano il comportamento; i registri delle decisioni spiegano l’intenzione. Entrambi sono necessari e lavorano insieme. Un test può far rispettare che le email generate dall’IA devono essere salvate come bozze, mentre un Registro delle Decisioni di Prodotto spiega che questo è richiesto perché gli utenti devono revisionare la comunicazione generata dall’IA prima che esca dal sistema. Il test protegge il comportamento. Il registro delle decisioni protegge il significato. Insieme, rendono i cambiamenti futuri più sicuri e prevedibili.

I registri delle decisioni non sono un sostituto dei commenti al codice

I commenti al codice spiegano i dettagli implementativi locali, mentre i registri delle decisioni spiegano decisioni più ampie. Usate i commenti per le linee sorprendenti, i casi limite, le soluzioni alternative e le funzioni che non possono essere semplificate. Usate i registri delle decisioni per spiegare perché esiste un’architettura, perché esiste un comportamento di prodotto, perché esiste un pattern di interazione e perché il team ha scelto una direzione piuttosto che un’altra. Se la spiegazione influenza solo poche righe, un commento è lo strumento giusto. Se influenza la direzione del sistema, un registro delle decisioni è lo strumento giusto.

Errori comuni

Scrivere registri troppo tardi

Un registro delle decisioni dovrebbe essere scritto quando la decisione viene presa, non mesi dopo quando tutti hanno dimenticato i compromessi. Va bene redigerne uno durante una pull request. È ancora meglio redigerlo prima dell’implementazione, mentre la decisione è ancora attivamente discussa e le alternative sono fresche.

Rendere i registri troppo lunghi

Un registro delle decisioni non è un saggio. Dovrebbe essere dettagliato abbastanza da preservare il giudizio ma breve abbastanza da essere effettivamente letto. Preferite la chiarezza alla completezza — un registro conciso che viene letto è molto più prezioso di uno completo che viene saltato.

Registrare decisioni senza conseguenze

La sezione delle conseguenze è il cuore del registro. Una decisione senza conseguenze dichiarate è spesso solo una preferenza piuttosto che una decisione reale. I buoni registri ammettono i compromessi onestamente, includendo cosa diventa più difficile o rischioso a causa della scelta.

Modificare i vecchi registri come se la storia fosse cambiata

Quando una decisione cambia, create un nuovo registro e segnate quello vecchio come sostituito. Riscrivere silenziosamente una vecchia decisione per farla corrispondere allo stato corrente distrugge il contesto storico che rende preziosi i registri delle decisioni. La storia è utile precisamente perché mostra come il pensiero si è evoluto. I knowledge base compilati affrontano il problema identico sotto un nome diverso — Manutenzione Wiki LLM: Deriva, Contraddizioni e Revisione la chiama deriva decisionale e applica la stessa regola di sostituire-invece-di-sovrascrivere alle pagine wiki.

Permettere ai registri generati dall’IA di unirsi senza revisione

L’IA può produrre un registro lucido e ben strutturato che è sottilmente sbagliato. Trattate i registri delle decisioni generati dall’IA esattamente come il codice generato dall’IA — revisionateli attentamente, verificate che la razionale sia accurata e assicuratevi che la sezione delle conseguenze rifletta ciò che il team ha effettivamente accettato.

Nascondere i registri fuori dal repository

Se i registri delle decisioni vivono in un wiki separato o in un sistema di documentazione, è meno probabile che vengano aggiornati insieme alle modifiche del codice e molto meno probabile che vengano letti dagli strumenti di coding IA che caricano il contesto per un compito. Conservarli nel repository non è solo una comodità — è ciò che fa funzionare la pratica per lo sviluppo assistito dall’IA.

Un modello operativo leggero

Un processo di team pratico che aggiunge un overhead minimo è questo:

1. Durante la pianificazione o l’implementazione, identificate se sta venendo presa una decisione significativa.
2. Chiedete a un assistente IA di redigere un ADR, PDR o DDR basato sulla discussione.
3. Revisionate la bozza come team, verificando contesto, alternative e conseguenze.
4. Committate il registro come Markdown nel repository.
5. Collegatelo dall’issue o dalla pull request correlata.
6. Istruite gli strumenti di coding IA a leggere i registri rilevanti prima di apportare modifiche future nell’area.
7. Sostituite i registri quando le decisioni cambiano, preservando il registro vecchio per la storia.

Questo non richiede una nuova burocrazia o un ruolo di documentazione dedicato. Richiede una piccola abitudine: preservare il giudizio importante nel momento in cui viene creato, vicino al codice dove sarà necessario.

Esempio di ADR

# Decisione: Utilizzare PostgreSQL per lo storage principale dell'applicazione

Stato: Accettata
Data: 2026-06-25
Tipo: Architettura
Responsabili: Team Piattaforma

## Contesto

L'applicazione ha bisogno di storage relazionale durevole per account, progetti,
permessi ed eventi di audit. Il team si aspetta query di reporting frequenti
e forti requisiti di consistenza per i controlli di permessi.

## Decisione

Utilizzeremo PostgreSQL come database principale dell'applicazione.

## Alternative considerate

### DynamoDB

Pro:
- Scalabilità operativa
- Adatto per pattern di accesso chiave-valore prevedibili

Contro:
- Più complesso per le query relazionali
- Più difficile per il reporting ad hoc
- Meno familiare al team corrente

### MySQL

Pro:
- Database relazionale maturo
- Modello operativo familiare

Contro:
- PostgreSQL corrisponde meglio alle esigenze del team per il supporto JSON,
  le opzioni di indicizzazione e l'esperienza esistente

## Conseguenze

PostgreSQL diventa una dipendenza operativa centrale. Il team deve gestire
le migrazioni con cura e monitorare le prestazioni delle query. In cambio,
l'applicazione ottiene un modello relazionale forte, indicizzazione matura e
supporto di reporting flessibile.

## Guida per l'IA

Quando si modificano il codice di persistenza, preferire il modello relazionale in PostgreSQL.
Non introdurre un secondo database principale senza un ADR sostitutivo.

Esempio di PDR

# Decisione: Le email generate dall'IA devono rimanere bozze

Stato: Accettata
Data: 2026-06-25
Tipo: Prodotto
Responsabili: Team Prodotto

## Contesto

Il prodotto può generare risposte email utilizzando l'IA. L'invio di email è un'azione
ad alta fiducia perché gli errori possono raggiungere clienti, partner o
team interni.

## Decisione

Le email generate dall'IA devono essere create come bozze. Un utente umano deve
revisionarle e inviarle.

## Alternative considerate

### Invio automatico

Pro:
- Flusso di lavoro più veloce
- Meno sforzo per l'utente

Contro:
- Rischio più elevato di messaggi errati o inappropriati
- Minore fiducia degli utenti
- Più difficile recuperare dagli errori

### Chiedere conferma solo dopo la generazione

Pro:
- Mantiene il flusso di lavoro semplice
- Fornisce un certo controllo all'utente

Contro:
- Incoraggia ancora una revisione superficiale
- Non si adatta al comportamento dei client email esistenti come le bozze

## Conseguenze

Il flusso di lavoro è leggermente più lento, ma più sicuro e affidabile.
L'automazione futura può migliorare la velocità di revisione, ma non deve bypassare
l'approvazione umana senza un PDR sostitutivo.

## Guida per l'IA

Quando si costruiscono funzionalità di generazione di email, creare bozze di default.
Non aggiungere invio automatico a meno che un nuovo PDR accettato non lo permetta esplicitamente.

Esempio di DDR

# Decisione: Mostrare i suggerimenti di scrittura dell'IA in un pannello laterale

Stato: Accettata
Data: 2026-06-25
Tipo: Design
Responsabili: Team Design

## Contesto

Gli utenti hanno bisogno di aiuto per migliorare i contenuti scritti, ma hanno anche bisogno di rimanere
in controllo del testo finale. Le modifiche inline dell'IA possono rendere difficile
distinguere i contenuti scritti dall'utente dalle suggerimenti generati.

## Decisione

I suggerimenti di scrittura dell'IA appariranno in un pannello laterale. Gli utenti possono accettare,
rifiutare o copiare i suggerimenti nell'editor principale.

## Alternative considerate

### Applicare i suggerimenti inline

Pro:
- Veloce
- Sembra integrato

Contro:
- Sfuma l'autorialità
- Rende la revisione più difficile
- Può sorprendere gli utenti

### Mostrare i suggerimenti in una modale

Pro:
- Esperienza focalizzata
- Facile da implementare

Contro:
- Interrompe il flusso di scrittura
- Più difficile confrontare suggerimento e testo originale

## Conseguenze

Il pannello laterale occupa più spazio sullo schermo, specialmente sugli schermi piccoli.
Tuttavia, preserva il controllo dell'utente e rende la revisione più chiara.

## Guida per l'IA

Quando si aggiungono funzionalità di assistenza alla scrittura, preservare la separazione tra
testo utente e suggerimenti dell'IA. Non applicare il testo generato direttamente
nel documento senza un'azione esplicita dell'utente.

Libreria di prompt suggerita

Utilizzate questi prompt per rendere i registri delle decisioni parte dello sviluppo quotidiano assistito dall’IA.

Trovare registri rilevanti prima di lavorare su una funzionalità:

Leggi docs/decisions e identifica qualsiasi registro delle decisioni accettato che si applichi
a questo compito. Riepiloga i vincoli prima di proporre modifiche al codice.

Redigere un nuovo ADR:

Redigi un Registro delle Decisioni Architetturali per questa decisione tecnica.
Includi contesto, decisione, alternative, conseguenze e guida per l'IA.
Tienilo conciso e specifico.

Redigere un nuovo PDR:

Redigi un Registro delle Decisioni di Prodotto per questo comportamento di prodotto.
Includi impatto utente, ambito, alternative, conseguenze e guida per l'IA.

Redigere un nuovo DDR:

Redigi un Registro delle Decisioni di Design per questo pattern di interazione.
Includi problema utente, alternative, compromessi, conseguenze e guida per l'IA.

Revisionare una pull request rispetto alle decisioni esistenti:

Revisiona questa pull request rispetto ai registri delle decisioni accettati in docs/decisions.
Identifica qualsiasi conflitto, registri delle decisioni mancanti o decisioni che dovrebbero
essere sostituite.

Sostituire una decisione:

Crea un nuovo registro delle decisioni che sostituisce quello esistente.
Preserva la razionale storica, spiega cosa è cambiato e collega entrambi i registri.

Letture correlate

• Il formato ADR originale di Michael Nygard — il post fondante che ha avviato il movimento ADR
• Organizzazione GitHub ADR — tooling, template e risorse della comunità per gestire i registri delle decisioni
• Cos’è lo Sviluppo Guidato dalle Specifiche? La Specifica come Fonte di Verità — la definizione canonica SDD che spiega come le specifiche delle funzionalità completano i registri delle decisioni: entrambi rendono l’intenzione durevole, a diversi livelli del sistema
• Sviluppo Guidato dalle Specifiche vs Vibe Coding: Waterfall? — quando utilizzare SDD e quando restare con flussi di lavoro più veloci e flessibili
• Architettura delle App in Produzione: Pattern di Integrazione, Design del Codice e Accesso ai Dati — la home del cluster che copre integrazione, testing, accesso ai dati e pattern di documentazione software
• IA per la Gestione della Conoscenza: Flussi di Lavoro Reali che Reggono — flussi di lavoro di conoscenza potenziati dall’IA pratici che completano la pratica dei registri delle decisioni